# 拾知：Jev 资料归档工作台

这是一个可运行的本地应用：导入文章或笔记，调用 Jev 判断类别、主题相关性和正文信息是否足够，人工复核后保存到 SQLite。它用于个人或小团队的首轮试点。

**当前交付已验证本地流程和接口契约；没有使用你的账户、没有调用真实 Jev，也没有验证真实中文分类准确率。** 默认的 `demo` 模式使用明确标注的关键词规则；这些数值不能当成 Jev 的性能数据。本地应用可以使用真实资料；开启 `typesafe` 模式后，模型推理在 TypeSafe 云端进行。

## 1. 启动

需要 Python 3.10 或更新版本。不需要安装第三方依赖。

**只验证流程时，运行 `python3 demo.py`。** 这个入口强制使用本地规则，忽略环境里的提供方与 API 密钥，并把付费调用预算设为 0。它不会调用 Jev API。

在项目目录运行：

```bash
python3 server.py
```

浏览器打开 [http://127.0.0.1:8765](http://127.0.0.1:8765)。`Ctrl+C` 停止服务。默认创建 `data/archive.sqlite3`，重启后资料仍然存在。端口占用时可用 `python3 server.py --port 8766`。

开始使用：

1. 修改侧栏“当前归档主题”，说明你要收集什么知识。
2. 点击“新建资料”粘贴正文，或“导入文件”选择 `.md` / `.txt` 文件。
3. 点击“分析这份资料”，或一次分析最多 20 份待处理资料。
4. 阅读原文，确认类别、是否相关，再点击“确认归档”或“跳过资料”。
5. 从“已归档”查看知识库，或导出 JSONL。调用账本记录本项目的用量与费用占用。

导入不会调用模型，复核与导出也不会调用模型。来源链接只记录，不抓取网页。正文限制为 12,000 字符且不超过 24 KB UTF-8；长文应按完整章节拆分。内置三份资料是合成示例，只能在演示模式加载。

`sample-articles/` 附有此前 Jev 技术博文拆分的 14 个章节，可直接选择并导入。这是已有正文素材，不是独立业务测试集，也不包含真实 Jev 分类结果。

## 2. 接入真实 Jev

先在 [TypeSafe 控制台](https://console.typesafe.ai/)申请账户、创建 API 密钥，并检查余额与充值设置。停止已有演示服务，在 **Bash** 中执行：

```bash
read -r -s -p 'TypeSafe API Key: ' TYPESAFE_API_KEY
export TYPESAFE_API_KEY
export JEV_PROVIDER=typesafe
export JEV_DAILY_BUDGET_USD=0.05
export JEV_MONTHLY_BUDGET_USD=0.50
python3 server.py
```

输入密钥时终端不回显；密钥不会传给浏览器、写进数据库或日志。不要把密钥发到聊天或提交到仓库。`.env.example` 是配置说明，程序不会自动加载 `.env`。界面显示“待配置密钥”时，点击分析会被本地拒绝，不会偷偷回退到演示结果。

接口固定为 `POST https://api.typesafe.ai/v1/systemone`，模型固定为 `jev-1.13.0`。`archive.py` 中的 `build_payload()` 定义三项问题，`TypeSafeProvider` 使用标准库调用 API。代码校验返回版本、类型、概率范围与分布、最大概率选项、加权分值和 `usage.input_tokens`。[官方 API 契约](https://docs.typesafe.ai/api)

类别包括 AI 与智能体、软件工程、硬件与物联网、产品与商业、其他资料。调整类别和判定规则时，需要同步修改 `CATEGORIES` 与 `RUBRIC_VERSION`，并用新的真实样本评测。主题可直接在界面修改。已有结果会保留当时主题；重新分析使用新主题。

## 3. 是否持续计费

截至 **2026-10-12**，官方 Jev 1.13 的公开价格为 **0.042 美元 / 百万输入 token，输出 token 免费**。每次输入都会消耗账户 Credits；没有模型请求时不产生输入用量费。应用保持打开、查看文章、归档、导出，都不调用模型。[官方模型价格](https://docs.typesafe.ai/models)

账户协议支持**自愿开启自动充值**：余额降到阈值或不足时，可能再次扣款充值。未开启时，余额耗尽可能拒绝生成结果。购买的 Credits 默认在合同期限结束或购买后 12 个月两者较早时到期，订单可另有约定；促销余额有各自发放条件。公开模式是按量消耗余额，具体订单与网关套餐仍须单独核对。[官方账户协议第 8.2 条](https://typesafe.ai/legal/mca)

假设正文、标题、主题、问题与选项合计 **每次实际消耗 2,000 输入 token**：

| 每月需要分析的资料 | 输入 token 总量 | Jev 费用估算 |
|---|---:|---:|
| 1,000 份 | 200 万 | $0.084 |
| 10,000 份 | 2,000 万 | $0.84 |
| 100,000 份 | 2 亿 | $8.40 |

公式：`费用 = 实际 input_tokens / 1,000,000 × 0.042`。这是用量场景计算，不是实测成本；不能把汉字数量直接当作 token 数量。以响应的 `usage.input_tokens` 和供应商账单为准。税费、网关加价、云服务器、OCR、向量索引或额外生成模型不在表内。当前项目在本机运行，不要求先租云服务器。

## 4. 成本控制如何工作

- **事件触发**：只在用户点击分析时调用，没有定时扫描或持续推理。
- **正文去重**：换行和 Unicode 规范化后计算 SHA-256；相同正文打开原资料。
- **结果缓存**：键包含提供方、固定模型、完整问题、正文、标题、主题和规则版本。演示缓存与真实 API 缓存隔离。
- **三项合并**：一个请求同时提交分类、相关性和完整度问题。
- **先占用预算**：按当前版本最大 64k 输入 token 预留每次 `$0.002688`，成功后按实际输入数量结算。SQLite 事务防止并发突破应用预算。
- **不明计费保留占用**：网络失败、进程中断或缺失用量时保留预留额。重启不会抹掉它。已知用量但答案无效的调用仍计入费用。
- **不自动重试、不自动充值**：出错后查看账本再手动处理。自动充值属于供应商账户设置，项目不会替你修改。

默认每日预算 `$0.05`、每月预算 `$0.50`，账期按 UTC。剩余预算必须足够覆盖整次预留额才能调用，可能比按正文估算更早停止。这些限制只覆盖本项目、当前配置价格和官方输入上限；它们不限制其他程序用同一密钥产生的费用，也不替代供应商账户预算。价格变化时更新 `JEV_PRICE_PER_MILLION_USD`。固定版本升级需同时复核输入上限与价格。

不明调用的人工核费方法：先停止服务，在供应商控制台核对实际请求与输入数量，然后执行：

```bash
python3 manage.py reconcile CALL_ID --input-tokens 1200 --note '依据供应商控制台记录核对'
```

`CALL_ID` 在账本中查看。明确未被计费时填写 `0`；不能仅凭“程序报错”推断未计费。核费会保存审计记录。再次启动服务查看更新。

## 5. 判断和复核规则

```mermaid
flowchart LR
  A[粘贴正文 / 导入 TXT 或 MD] --> B[校验与正文去重]
  B --> C{相同请求有缓存?}
  C -->|有| F[形成复核建议]
  C -->|无| D[原子预留预算]
  D --> E[Jev: Choice / Score / Noul]
  E --> F
  F --> G[人工阅读与标签确认]
  G --> H[SQLite 归档 / 跳过]
  H --> I[JSONL 导出与评测]
```

分类建议使用**选中项概率**，不是 API 的 `confidence`。相关性使用 Score 的 `P(等级 2)+P(等级 3)`，不是只看平均分。正文足够使用 Noul 的 yes 概率。分类概率和正文足够概率均达到 0.8，且相关概率达到 0.8 时建议保留；相关概率不超过 0.2 时建议跳过；其他情况提示人工判断。

**这些阈值是首版试点的起点，未经你的业务数据校准。所有建议仍进入人工复核，项目不会自动归档或删除原文。** 提示语中的“忽略正文指令”只是减轻干扰，不能保证抗提示注入。

在真实使用前，建议准备 200 份覆盖各类别、无关资料、短文、混合主题和边界样本的中文文章，由人工标注。将规则调整集与独立测试集分开；重点测错误归档率、漏收率、复核比例、P95 延迟和平均实际费用。样本数是试点建议，不构成统计保证。固定模型升级、类别调整或换主题后重新测。

导出所有资料后，可以查看已有复核标签的描述性指标：

```bash
curl 'http://127.0.0.1:8765/api/export?status=all' -o reviewed.jsonl
python3 evaluate.py reviewed.jsonl
```

默认排除演示结果；`--include-demo` 仅检查流程。输出类别准确率、阈值覆盖率、接受集合错误率和相关性 Brier 分数。这里只反映已复核资料，可能有选择偏差；不同主题与版本应分组。不能直接当成上线保证。

## 6. 数据、备份与部署边界

- 原文、来源、分析快照、人工标签和审计记录保存在本机 SQLite。默认数据库不打包、不提交仓库。
- 真实模式会把**标题和正文**发给 TypeSafe；本地保存不意味着推理不出本机。来源链接不发给模型。
- 默认只监听 `127.0.0.1`，检查 Host、Origin 和会话令牌；不提供公网或多人身份认证。不要直接把端口暴露到公网。
- 前端把文章作为纯文本展示；来源 URL 只允许 HTTP(S)，没有自动网页抓取。
- 首版面向个人试点或人工操作的小团队，界面读取完整资料列表。大规模使用需要分页、异步任务队列、账户权限与经过验证的采集器。

使用 SQLite 在线备份接口：

```bash
python3 manage.py backup backups/archive-snapshot.sqlite3
```

目标文件已存在时不会覆盖。恢复时停止服务，用已核验备份替换数据库，再启动。多台设备共享时应进一步设计服务端权限、备份与恢复流程。

## 7. 适合扩展的领域

这是根据任务形态和可验证程度做的工程选型判断；具体准确率需用各自数据确认。[官方用例目录](https://docs.typesafe.ai/concepts/use-case-map)

| 领域 | Jev 负责的判断 | 其余系统负责的工作 |
|---|---|---|
| 技术资料与研究知识库 | 分类、主题匹配、纳入标准筛选 | 采集、正文提取、复核、存储与检索 |
| 客服工单 | 意图、部门、紧急程度、资料是否齐全 | 订单查询、指派、回复生成、人工升级 |
| 电商资料与售后 | 商品类目、诉求类型、缺失凭证 | 金额计算、规则核验、退款执行 |
| RAG 与搜索 | 候选文本相关性、证据是否支持问题 | 索引、候选召回、去重、引用和答案生成 |
| 智能体工作流 | 工具选择、请求路由、升级人工判断 | 参数校验、执行权限、工具调用和结果确认 |

首个项目选择资料归档的理由是有固定输出、有人工真值、错误易于发现且修正，成本也容易记录。开放式长文生成、精确金额计算、OCR 和全自动复杂规划需要其他组件；Jev 不独自完成这些工作。

## 8. 检查与文件

```bash
python3 -m unittest discover -s tests -v
```

26 项测试覆盖去重、缓存持久化、主题失效、演示隔离、预算并发、超时占用、版本与响应校验、人工标签、HTTP 访问限制、导出、备份和人工核费。使用固定接口响应验证接入逻辑，不产生付费调用。浏览器验证通过导入、复核、导出、主题修改和纯文本展示检查；320、390、736、1024、1440 像素宽度均无横向溢出。详情见 `verification.json`。

| 文件 | 用途 |
|---|---|
| `server.py` | 本地 HTTP 服务与接口 |
| `demo.py` | 强制本地规则的验证入口，忽略密钥和付费模式 |
| `archive.py` | Jev 提供方、规则、持久化、缓存和预算 |
| `static/` | 无构建依赖的浏览器界面 |
| `evaluate.py` | 人工标签的描述性指标 |
| `manage.py` | 一致备份与不明费用核对 |
| `tests/` | 本地自动化验证 |

此交付是可接真实 API 的本地试点。开启真实模式并用自己的资料完成验证之后，才能评估业务效果和扩大自动化范围。