能源数据采集平台
完整使用手册

01 · START HERE

地址与入口

02 · ACCOUNT

账号与权限

门户使用自建用户名和密码账号，无需绑定手机号、邮箱或短信验证码；注册成功后会自动登录。

1. 打开正式门户，首次使用选择“直接注册”。
2. 填写用户名、至少 10 个字符的密码和可选显示名称。
3. 选择“注册并进入网站”；已有账号直接登录。
4. 内部测试期间，新注册账号自动获得管理员权限。

密码明文不会写入数据库或日志。连续五次输入错误会锁定账号 15 分钟；已经签发的个人 API 密钥仍可继续使用。

03 · PLAN DATA

分析所需数据源

在首页展开“数据需求分析”，输入研究、预测或建模目标。这个输入与采集任务共用；页面会识别来源机构、国家/地区和能源类型，并立即从实时已审批目录中匹配数据源，再按目标价格、供需、库存、市场、宏观、天气和政策事件说明推荐理由。

1. 写明能源品种、市场范围、分析目标和希望考虑的变量。
2. 核对来源机构、内容、数据源 ID、核心或补充角色。
3. 可以直接输入“国家统计局”“国家能源局”“美国能源信息署 EIA”“世界银行”等机构名称；同时写能源类型或指标时，系统只保留该机构中符合条件的来源。
4. 直接提交采集，系统会自动使用推荐来源；在采集区手动勾选来源时，以手动选择为准。
5. 采集完成后，数据交付会自动使用本次任务的数据源和日期范围。
6. 遇到“尚缺的数据类型”时，将其作为后续接入事项，不要用不相关来源替代。

采集执行期间，分析结果会继续显示，便于同时核对推荐来源、缺口与任务进度。

系统只处理能源领域需求。农业、股票、房地产等非能源议题会被明确拒绝，不会被强行映射到能源来源。“预测”或“趋势”也不会自动展开全部变量，页面优先遵循需求中明确写出的价格、供需、库存、市场、宏观、天气和政策条件。

预测国际原油价格，需要价格、供需、库存、美元指数、天气和政策事件。

04 · READ DATA

查询数据库中的现有数据

先从“数据目录”找到准确 ID

1. 在首页找到“只读数据 API”。
2. 选择“数据目录”，将返回条数设为 100。
3. 发送查询并复制需要的 source_id。
4. 再切换到“指标数据”或“文档元数据”。
5. 填写 ID、开始日期、结束日期和返回条数。

查询为零时

切换到“覆盖统计”，核对该来源的记录数、最早日期和最晚日期。零记录不等于故障，也可能是日期不在覆盖范围或上游尚未发布。

05 · COLLECT

发起采集任务

1. 先注册或登录账号。
2. 展开“采集任务”，写清能源主题和完整日期。
3. 需要精确控制时，展开“指定数据源”并勾选来源。
4. 提交后任务会保存在服务器；可关闭页面，再次登录后会自动恢复进度。
5. 可使用“暂停任务”“继续任务”和“取消任务”；暂停会在当前批次安全结束后生效。
6. 记录 run_id，核对发现、新增、跳过和失败数量。

可以直接复制的要求

采集2025年1月1日至2025年3月31日的国家统计局月度能源生产数据。

采集2025年全年的国家能源局全社会用电量。

采集2025年第一季度的天然气价格和库存数据。

采集2026年7月1日至2026年7月31日的国家能源局政策元数据。

06 · LONG RANGE

长时间范围和分批采集

门户可以提交任意长的正式日期范围。服务器会按最多 30 天持久化拆分；选择多个来源时，每个来源会得到独立子任务。临时失败会按退避策略自动重试，页面关闭或服务重启不会丢失进度。

• 新数据源预览验证：最多 31 天，且不入库。
• 单个后端正式请求：默认最多 90 天。
• 门户长任务：主动拆成最多 30 天的小窗口。

多年回填建议按年、季度或月执行。保存每一批的 run_id，只重试失败窗口。

07 · DELIVERY

生成并下载标准化数据包

1. 展开“标准化数据交付”。
2. 选择“数据库现有数据”或“本次任务数据”。
3. 数据库模式可检索来源并设置日期；本次任务模式使用服务器锁定的日期、来源和指标范围。
4. 点击“生成标准化数据包”。
5. 显示“数据包已就绪”后，可以单独下载主 CSV，也可以下载包含清单、SQLite 和结构说明的完整 ZIP。

“单独下载 CSV”会从同一份任务绑定数据包中提取主指标 CSV；没有指标时会下载文档元数据 CSV。“下载完整数据包”则包含合并 CSV、SQLite、清单，以及存在相应记录时按核心、补充或手动来源拆分的 CSV。清单逐年列出记录数，零记录年份也会明确显示。数据包不包含原始网页、原始响应、内部配置、密钥、分析结论或摘要。下载通常在 24 小时内有效。

08 · FIND SOURCES

模糊搜索和选择数据源

在数据库导出区，可以输入来源机构、来源网站、主题或精确 ID。多个关键词用空格分开，并按“同时满足”处理。

例如输入“国家能源局 政策”，会比只输入“政策”更精确。界面仍会保留原始数据源 ID，复制时不要翻译或改名。

09 · SOURCE ADMIN

管理员添加网站、RSS 或 API

1. 进入“数据源管理”，点击“新建草稿”。
2. 填写不可变 ID、包含来源机构的显示名称、类型、类别、官方 URL 和频率。
3. 填写精确域名白名单和声明式 JSON 配置，然后保存。
4. 选择不超过 31 天且已知有数据的范围，运行预览验证。
5. 核对识别条数、字段和“未写入数据库”的提示。
6. 检查许可、频率和操作审计，再审批并启用。
7. 首次正式采集小范围，并用覆盖统计复核。

JSON API 草稿结构

{
  "source_id": "demo_oil_price",
  "source_name": "示例能源机构 - 原油价格",
  "source_type": "api",
  "category": "oil",
  "entry_url": "https://api.example.org/energy/prices",
  "frequency": "daily",
  "parser_name": "generic_api",
  "allowed_domains": ["api.example.org"],
  "config": {
    "base_url": "https://api.example.org/energy/prices",
    "query_params": {"start": "{start_date}", "end": "{end_date}"},
    "items_path": "items",
    "field_mapping": {
      "metric_name": "name", "region": "region",
      "period": "date", "value": "value", "unit": "unit"
    },
    "data_format": "json",
    "record_frequency": "daily"
  }
}

example.org 仅用于说明，不能直接审批。配置中禁止填写真实密钥、Cookie、Authorization、命令、脚本、通配域名或私网地址。

09B · RULE EVOLUTION

管理员规则实验室

规则实验室用于整理错误推荐、自动迭代候选并制作待审核版本，不会直接修改生产推荐逻辑。

1. 使用管理员账号进入“规则实验室”。
2. 在“加入匿名纠错”中填写错误需求、实际来源 ID 和期望来源 ID。
3. 检查页面报告的脱敏数量；访问码、Token、邮箱、手机号和 URL 查询参数不会进入审阅包。
4. 使用“把某个表达识别为某个机构、主题或地区”的句式生成候选。
5. 同时提供一个应当改善的正向案例和一个不得改变的防误识别案例。
6. 系统自动比较三种策略，并对扰动后的正向和防误识别案例运行 100 轮测试。
7. 只有 100 轮全部通过时，才能选择“接受为待实现候选”。
8. 点击“下载审阅包”保存当前批次；刷新页面前未下载的内容不会保留。

接受候选只记录审阅决定。候选仍须加入代码、执行完整回归并获得明确发布授权，才可能影响公网门户。

10 · DEVELOPERS

数据 API 与 Swagger

登录后打开“个人 API”，可以创建、测试和撤销自己的密钥，并直接复制 curl、Python 或 JavaScript 示例。Swagger 用于查看公开 API 的路径、参数和响应结构；管理接口故意不出现在其中。

export ENERGY_PERSONAL_API_KEY='创建后仅显示一次的个人密钥'

curl -sS -G \
  'https://test.w2764362942.com/v1/energy/data/metrics' \
  -H "Authorization: Bearer $ENERGY_PERSONAL_API_KEY" \
  --data-urlencode 'source_id=nbs_energy_production_monthly' \
  --data-urlencode 'start_date=2025-01-01' \
  --data-urlencode 'end_date=2025-12-31' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'offset=0'

完整个人密钥只在创建时显示一次。先使用页面中的“测试密钥”确认连接，再保存到环境变量或秘密管理服务；不要提交到代码仓库。

11 · OPENCLAW

OpenClaw 使用方法

OpenClaw 使用自然语言调用固定工具，只访问已批准目录，不会临时运行命令或访问任意网址。

查找与“石油”有关的已批准数据源，列出中文名称、来源网站、source_id、类型和更新频率，不要分析数据。

查询 nbs_energy_production_monthly 在 2025-01-01 到 2025-12-31 的标准化指标，返回日期、值、单位、来源网址、发布时间和采集时间。

查看 nea_electricity_consumption 的记录总数、最早日期和最晚日期，不做趋势判断。

12 · DATA MEANING

字段和时间含义

做预测模型时必须按当时已经发布的数据构造样本，避免未来信息泄露。比较数据前还要核对地区、频率、统计口径和单位。

13 · TROUBLESHOOTING

常见错误处理

14 · GUARDRAILS

安全与合规边界

• 不在聊天、截图、Git、网页代码或终端历史中写真实密钥。
• 后端密钥只保存在服务器或 Cloudflare Secrets，浏览器只访问固定门户路由。
• 不把 PostgreSQL、内部采集接口或 OpenClaw Gateway 暴露到公网。
• 不允许用户提交任意 URL、工具名、命令或请求头。
• 不绕过登录、验证码、付费墙、robots.txt 或反爬限制。
• 新闻对外只共享元数据；平台输出数据，不输出预测或决策结论。