Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
@@ -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/<run_id>.local.json` 的关键字段、trace_id、报错全文。
**先脱敏**(不要贴 key、被测回答原文)。
render: text
validations:
required: false

- type: dropdown
id: eval_impact
attributes:
label: 是否影响评测结论
options:
- 是(结论被伪造 / 误判 / 无法复现)
- 否(安装 / CLI / 文档 / 环境)
- 不确定
validations:
required: true
11 changes: 11 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -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: 不知道该看哪份文档时从这里进
54 changes: 54 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.yml
Original file line number Diff line number Diff line change
@@ -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
37 changes: 37 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
## 改动

<!-- 一句话说明;列出关键文件。一个 PR = 一个完整任务。 -->

## 关联

<!-- Closes #<issue> / refs #<issue>;没有 issue 就写“无” -->

## 验证证据(必须)

- [ ] 测试命令与结果:`________`(通过几 / 失败几)
- [ ] 覆盖率(若改实现):`________`
- [ ] 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 只含本任务改动
69 changes: 69 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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、目录骨架。
25 changes: 19 additions & 6 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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%`。
> ⚠️ **锚点里<u>不写死</u>那些"每次合并都会变"的值** —— 主要是 **commit sha**
> (实测:2026-09-21 → 09-24,三天里锚点的 `main` sha 就旧了一截)。
Expand Down Expand Up @@ -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**。
>
Expand Down
81 changes: 81 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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。
21 changes: 21 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -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.
Loading
Loading