# agent-poc

**Repository Path**: zeus-maker/agent-poc

## Basic Information

- **Project Name**: agent-poc
- **Description**: agent-poc
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-20
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 内蒙古电力行业招标评标 AI 助手管理端

可本地或服务器部署的评标 POC。**主入口是「评标 AI 助手」**：用自然语言指挥 AI 逐步评分、展示证据、生成排名与报告；评测规则可封装为**技能**，挂载电力专家知识包。

| 文档 | 说明 |
| --- | --- |
| [产品 PRD](docs/PRD.md) | 定位、架构、演示脚本、优先级 |
| [部署教程](docs/DEPLOY.md) | Docker 一键部署、环境变量、Nginx、升级回滚 |
| [用户操作指南](docs/user-guide/用户操作指南.md) | 逐步截图教程（评标全流程、@/ 引用、复核与报告） |

**重要定位：** AI 只做**辅助评标**，不替代评标委员会。所有分数须可追溯、可解释、可人工复核；无证据时输出「无法判断」，禁止编造。

---

## 界面预览

### 登录与导航

登录后默认进入 **评标 AI 助手**。左侧为功能导航，顶栏显示当前用户与角色。

| 登录页 | 系统导航 |
| --- | --- |
| ![登录页](docs/user-guide/images/01-login.png) | ![系统导航](docs/user-guide/images/02-nav.png) |

默认账号见下文 [默认账号](#默认账号)（密码均为 `123456`）。

### 资源包与文件准备

评标前在 **资源包** 中创建项目，上传招标文件、登记投标商并上传标书。系统可 AI 提取招标项与评分项。

| 资源包列表 | 招标文件上传与招标项识别 | 投标商与标书 |
| --- | --- | --- |
| ![资源包](docs/user-guide/images/03-packages.png) | ![招标上传](docs/user-guide/images/04-tender.png) | ![投标商](docs/user-guide/images/06-bidders.png) |

### 评标 AI 助手（核心流程）

**① 新建评标** 圈定供应商与招标项 → **② 对话下指令** → **③ 确认计划（按此执行）** → **④ 查看步骤与证据** → **⑤ 生成报告 / 网页 / Excel**

| 助手主页 | 新建评导向导 | 计划确认 |
| --- | --- | --- |
| ![助手主页](docs/user-guide/images/07-assistant-home.png) | ![新建评标](docs/user-guide/images/08-new-eval.png) | ![计划确认](docs/user-guide/images/10-plan-confirm.png) |

| 步骤卡与证据预览 | HTML 报告预览 |
| --- | --- |
| ![步骤与证据](docs/user-guide/images/11-steps-evidence.png) | ![HTML 预览](docs/user-guide/images/12-html-preview.png) |

- **@** 引用已上传文件；**/** 唤起可选技能（内置「电力智能评标」默认静默生效，不在 `/` 列表中）
- 文件上传在输入框左下角，只存二进制；Agent 通过 `read_file` 在后端读取 PDF
- 涉及改分的计划须点 **「按此执行」** 才会写入；解释类追问不改分
- 生成网站时，对话里可折叠查看实时 HTML 源码；生成结束或中途停止后，源码仍保留在该条消息中，可再展开、复制或预览

| @ 引用文件 | / 唤起技能 |
| --- | --- |
| ![@ 引用](docs/user-guide/images/13-mention-file.png) | ![/ 技能](docs/user-guide/images/14a-skill-slash.png) |

### 排名、报告与复核

| 排名与图表 | 评标报告 | 待复核 |
| --- | --- | --- |
| ![排名](docs/user-guide/images/17-ranking.png) | ![报告](docs/user-guide/images/18-report.png) | ![复核](docs/user-guide/images/19-review.png) |

> 更多界面与逐步操作见 **[用户操作指南](docs/user-guide/用户操作指南.md)**（含技能工坊、专家知识库、系统设置等截图）。

---

## 这个系统能做什么

1. **资源包**：一个招标项目/标段，挂招标文件、投标商、评分项。
2. **招标解析**：上传招标文件，AI 提取招标项、评分项、否决项、价格分公式；可一键导入内置滨江样例。
3. **投标解析**：为每家投标商上传标书，提取资质、业绩、参数等（或助手内 `read_file` 读 PDF）。
4. **专家知识库**：五类电力专家资源包（资质、设备标准、施工规范、蒙电制度、案例）。
5. **技能工坊**：把评测规则做成技能，挂载专家包；对话中用 `/` 引用。
6. **评标 AI 助手**：对话式评标、计划确认、步骤卡与证据预览、流式 Markdown、HTML/Excel 报告。
7. **横向对比**：各家资质/参数/风险对照（部分为示范数据）。
8. **排名汇总**：技术/商务/价格加权总分与图表。
9. **人工复核**：主观分与低置信度项须确认；改分留审计。
10. **导出**：网站报告、Excel 对比表、CSV（未复核时带草稿水印）。

---

## 安装与启动

### 服务器一键部署（Docker，推荐）

```bash
curl -fsSL https://gitee.com/zeus-maker/agent-poc/raw/main/scripts/deploy.sh | bash
```

带 API Key：`DEPLOY_AI_API_KEY=你的key curl -fsSL ... | bash`

详见 **[部署教程](docs/DEPLOY.md)**（环境变量、持久化、systemd、Nginx）。

### 本地开发

需要 [Node.js 18+](https://nodejs.org/)（LangGraph 流式助手建议 **22+**）。

```bash
npm install
npm run dev
```

浏览器打开 [http://localhost:3000](http://localhost:3000)。首次启动自动建库并写入示范数据。重置示范：

```bash
npm run db:reset
```

### 手动 Docker

```bash
cp .env.example .env   # 配置 JWT_SECRET、AI_API_KEY
docker compose up -d --build
```

---

## 默认账号

| 用户名 | 密码 | 角色 | 能做什么 |
| --- | --- | --- | --- |
| admin | 123456 | 管理员 | 全部权限 |
| expert | 123456 | 评标专家 | 评标、打分、查看证据 |
| reviewer | 123456 | 复核人 | 复核、修改分数、填写意见 |
| observer | 123456 | 观察员 | 只读 |

---

## 建议演示路径

预置项目：**内蒙古某 220kV 变电站设备采购**（`NMG-EPC-2026-0220`）。

1. `admin / 123456` 登录 → 进入评标 AI 助手。
2. 点 **「新建评标」**：选招标包、参评供应商、招标项与权重 → **开始评标**。
3. 发送指令（或点快捷入口）→ 核对计划 → **按此执行**。
4. 查看步骤卡与右侧证据预览；可说「生成 HTML 网站」打开报告预览。
5. **待复核** 处理主观分；**排名报告** 看总分。

示范结论（便于讲解）：

- **丙**：无承装（修、试）电力设施许可证 → **否决废标**，总分 0。
- **甲**：资质与 220kV 业绩齐全，主观分已确认。
- **乙**：业绩电压偏弱，主观分待复核。
- **价格分**由规则引擎计算，不由大模型算。

---

## 核心规则（评标人员）

| 规则 | 说明 |
| --- | --- |
| 否决项 | 命中即废标，总分 0，不参与排名 |
| 客观分 | 规则 + 证据，可直接计算 |
| 主观分 | AI 只给建议，须人工确认后生效 |
| 价格分 | 基准价 = 有效报价算术平均；高 1% 扣 1 分，低 1% 加 0.5 分；超限价否决 |
| 总分 | 技术×权重 + 商务×权重 + 价格×权重 |
| 待复核 | 置信度 < 0.7 或主观项 |
| 排名 | 总分降序；同分先比价格分，再比技术分 |

---

## 接入大模型

默认 **DeepSeek**（`https://api.deepseek.com/v1`，`deepseek-chat`）。在 **系统设置** 可配置多套模型、**测连接**、设为当前使用。密钥写在 `.env` 的 `AI_API_KEY` 或设置页，**勿提交 git**。

![系统设置](docs/user-guide/images/22-settings.png)

- 助手走 **LangChain + LangGraph**，SSE 流式输出；未配 Key 会提示，不走 Mock 剧本。
- `AI_MOCK=true` 时部分**文件解析**仍可用本地示范；**对话始终走真实模型**。
- AI 输出经 Zod 校验；失败重试一次，仍失败则标「待复核」。价格分始终由规则引擎计算。

---

## 页面一览

| 地址 | 作用 |
| --- | --- |
| `/login` | 登录 |
| `/assistant` | **评标 AI 助手（主入口）** |
| `/dashboard` | 工作台概览 |
| `/packages` | 资源包列表 |
| `/packages/[id]/tender` | 招标文件上传与解析 |
| `/packages/[id]/criteria` | 评分项编辑 |
| `/packages/[id]/bidders` | 投标商与标书 |
| `/packages/[id]/compare` | 横向对比 |
| `/packages/[id]/ranking` | 排名与图表 |
| `/packages/[id]/report` | 可打印报告 |
| `/knowledge` | 专家知识库 |
| `/skills` | 技能工坊 |
| `/review` | 待复核 |
| `/settings` | 模型与系统提示词 |
| `/audit` | 审计日志 |

---

## 技术栈

| 层 | 技术 |
| --- | --- |
| 前端 | Next.js 14、TypeScript、Tailwind、shadcn/ui |
| 后端 | Next.js Route Handlers |
| 数据库 | Prisma + SQLite |
| Agent | LangChain、LangGraph、`read_file` 工具、内置 `skills/power-bid-evaluator/` |
| 部署 | Docker Compose、`scripts/deploy.sh` 一键脚本 |

```bash
npm run setup      # 建库 + 种子
npm run db:seed    # 仅种子
npm run db:reset   # 清空并重置
npm run dev        # 开发服务器
```

---

## 已知边界（POC）

- 上传文件本地存储，无病毒扫描；扫描件 PDF 无法提取文字。
- 登录为 Cookie + JWT 简化会话，非完整 IAM。
- 已复核分数不会被技能重跑覆盖；未复核报告显示草稿水印。
- 评分/否决计划须 **按此执行** 才写入；解释类追问直接查证据不改分。
- 真实 PDF 版面解析、签章核验、与正式评标系统对接不在本 POC 范围。

完整需求与路线图见 [docs/PRD.md](docs/PRD.md)。

---

## 开发日志

功能收尾写入 `docs/devlog/`，一条日志对应一次 git commit。约定见 `.cursor/rules/devlog-required.mdc`。