企业官网建设流程全解析

1. 为什么数据分析师需要一个 Agent Harness

如果你每周一早上都要花三四个小时从 MySQL、ClickHouse、广告后台、多维表格里拉数据、对齐口径、做透视表、写分析、发群，那你大概率已经想过用脚本自动化。但真正动手之后会发现，单纯写个 Python 脚本挂在服务器上跑，问题比想象中多得多：脚本挂了没人知道，改个口径要登服务器改代码，日志散落在各处，权限管理基本靠自觉。

这就是为什么我们需要一个 Agent Harness。Harness 在这里不是某个具体产品，而是指一套「任务编排 + 工具调用 + 状态管理 + 可观测」的骨架。它把 Agent 的推理能力和工程化的调度、重试、告警、日志串起来，让自动化报表从「能跑」变成「敢让它自己跑」。

具体来说，一个面向自动化数据分析报表的 Agent Harness 需要解决四件事。第一是任务编排：什么时候触发、先拉哪个数据源、失败了怎么重试。第二是工具调用：Agent 需要能调数据库、调大模型、调推送接口，这些工具要统一注册、统一鉴权。第三是状态与上下文：上一周的数据、历史均值、异常标记，这些要能在多轮调用之间传递。第四是可观测：每一步的输入输出、耗时、报错都要留痕，出问题能快速定位。

我试过用纯 crontab + 脚本的方式跑过一段时间，最大的坑不是代码写不出来，而是「静默失败」。脚本半夜跑挂了，第二天早上没人知道，等到业务方来问报表怎么没发，已经过去好几个小时。Harness 的价值就在于把失败变成显式事件，触发告警、记录日志、甚至自动重跑。

对于数据分析师和后端工程师来说，搭建 Harness 的另一个好处是统一 Key 管理。报表 Agent 要调多个模型、多个数据源，如果每个地方都散落着 API Key，安全性和维护成本都很高。用 TaoToken 这类统一接入层，可以把模型调用的 Key 收敛到一个地方，Harness 里只配置一个 Base URL 和一个 Key，换模型、加模型都不用改业务代码。

这一篇会带你从零搭一个能跑通端到端报表的 Harness，包含可复制的配置片段、统一 Key 接入方式，以及一组样例数据的验证动作。你不需要是 Agent 专家，只要会写基本的 Python 和 SQL 就能跟上。

2. TaoToken 统一 Key 接入与 Harness 前置准备

在动手写 Harness 之前，先把模型调用的接入层搞定。自动化报表 Agent 的核心智能部分——异常分析、自然语言解读、口径对齐建议——都要调大模型。如果直接用各家厂商的原生 SDK，你会遇到几个麻烦：不同厂商的接口格式不一样，Key 管理分散，换模型要改代码，成本也不好统一看。

TaoToken 的思路是提供一个兼容 OpenAI 接口规范的统一入口，你只需要一个 Base URL 和一个 API Key，就能调用多个模型。对 Harness 来说，这意味着模型调用这一层可以抽象成一个统一的 client，业务代码里不用关心底层是哪个模型。

先拿到 Key。访问 https://taotoken.net/api-keys 创建一个 API Key，建议按项目命名，比如report-agent-prod，方便后续做用量区分。创建之后复制保存，这个 Key 只显示一次。

Base URL 用https://taotoken.net/api，注意这个地址不带任何查询参数。模型 ID 按你实际要用的填，比如做数据分析报告可以用claude-sonnet-4-20250514或者gpt-4o，具体可用列表在 https://taotoken.net/doc 里能查到。

Harness 的前置准备还包括运行环境。我建议用 Python 3.10 以上，依赖装这几个：

pip install openai pandas pymysql clickhouse-driver plotly python-dotenv requests

openai这个包用来调 TaoToken 的兼容接口，pandas做数据清洗和指标计算，pymysql和clickhouse-driver分别连 MySQL 和 ClickHouse，plotly生成图表，python-dotenv管理本地环境变量，requests做推送。

环境变量文件.env这样写：

# TaoToken 统一接入 TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_API_KEY=sk-你的key TAOTOKEN_MODEL=claude-sonnet-4-20250514 # 数据源 MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=report_reader MYSQL_PASSWORD=你的密码 MYSQL_DB=analytics CLICKHOUSE_HOST=127.0.0.1 CLICKHOUSE_PORT=8123 CLICKHOUSE_USER=default CLICKHOUSE_PASSWORD=你的密码 CLICKHOUSE_DB=behavior # 推送 FEISHU_WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/xxx

这里有个细节要注意：数据源账号建议用只读账号，Harness 里的 Agent 只做查询不做写入，权限最小化能避免很多误操作风险。TaoToken 的 Key 也不要硬编码在代码里，统一走环境变量或者 Harness 的密钥管理。

Harness 的目录结构建议这样组织：

report-harness/ ├── .env ├── config/ │ └── harness.yaml ├── tools/ │ ├── db_tool.py │ ├── llm_tool.py │ └── notify_tool.py ├── agent/ │ └── report_agent.py └── main.py

config/harness.yaml是 Harness 的核心配置，把任务步骤、工具、重试策略都写进去。这样做的目的是让编排逻辑和业务代码分离，改流程不用动 Python。

3. 可复制的 Harness 配置与 Agent 编排片段

这一节给出可以直接复制的配置片段。先看config/harness.yaml：

harness: name: weekly-report-agent schedule: "0 8 * * 1" # 每周一早上8点 timeout_seconds: 1800 retry: max_attempts: 3 backoff_seconds: 30 steps: - id: pull_data tool: db_tool.pull_all params: start_offset_days: 7 on_failure: alert - id: validate_data tool: db_tool.validate depends_on: [pull_data] on_failure: alert - id: generate_charts tool: chart_tool.render depends_on: [validate_data] - id: llm_analysis tool: llm_tool.analyze depends_on: [validate_data] params: model: ${TAOTOKEN_MODEL} base_url: ${TAOTOKEN_BASE_URL} - id: notify tool: notify_tool.push depends_on: [generate_charts, llm_analysis] on_failure: alert

这个配置里，schedule用标准 cron 表达式，retry定义了失败重试策略，steps里每个步骤通过depends_on声明依赖关系。Harness 会按依赖顺序执行，某一步失败就触发on_failure定义的告警动作。

接下来是工具层的实现。先看tools/llm_tool.py，这是统一 Key 接入的关键：

import os from openai import OpenAI client = OpenAI( base_url=os.getenv("TAOTOKEN_BASE_URL"), api_key=os.getenv("TAOTOKEN_API_KEY"), ) def analyze(data_summary: str, abnormal_metrics: list) -> str: abnormal_text = "\n".join(m["msg"] for m in abnormal_metrics) or "无异常" prompt = f"""你是资深业务数据分析师。根据以下数据生成周报分析： 1. 用3句话概括本周业务表现 2. 针对异常指标分析可能原因 3. 给出1-2条可落地建议 数据摘要： {data_summary} 异常指标： {abnormal_text} 要求：所有分析必须基于给定数据，不确定的原因标注"可能"，不要编造事实。控制在300字以内。""" resp = client.chat.completions.create( model=os.getenv("TAOTOKEN_MODEL"), messages=[{"role": "user", "content": prompt}], temperature=0.3, ) return resp.choices[0].message.content

注意这里base_url和api_key都从环境变量读，模型 ID 也是。换模型只需要改.env里的TAOTOKEN_MODEL，代码一行不用动。这就是统一 Key 接入的价值。

再看tools/db_tool.py的数据拉取和校验：

import os import pandas as pd import pymysql import numpy as np from datetime import datetime, timedelta def pull_all(start_offset_days: int = 7): end = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0) end = end - timedelta(days=end.weekday() + 1) start = end - timedelta(days=start_offset_days - 1) conn = pymysql.connect( host=os.getenv("MYSQL_HOST"), port=int(os.getenv("MYSQL_PORT")), user=os.getenv("MYSQL_USER"), password=os.getenv("MYSQL_PASSWORD"), database=os.getenv("MYSQL_DB"), ) sql = f""" SELECT dt, new_user_count, dau, order_count, pay_amount, roi FROM dws_business_daily WHERE dt BETWEEN '{start:%Y-%m-%d}' AND '{end:%Y-%m-%d}' """ df = pd.read_sql(sql, conn) conn.close() return df, f"{start:%Y-%m-%d} 至 {end:%Y-%m-%d}" def validate(df: pd.DataFrame) -> list: issues = [] if df.isnull().any().any(): issues.append({"type": "missing", "msg": "数据存在空值"}) if len(df) != 7: issues.append({"type": "missing", "msg": f"应有7天数据，实际{len(df)}天"}) for metric in ["new_user_count", "dau", "order_count", "pay_amount", "roi"]: values = df[metric].tolist() if len(values) < 2: continue mean, std = np.mean(values), np.std(values) if std == 0: continue z = (values[-1] - mean) / std if abs(z) > 3: issues.append({ "type": "abnormal", "metric": metric, "msg": f"{metric} 偏离度 {z:.2f}，当前值 {values[-1]:.2f}，均值 {mean:.2f}", }) return issues

validate里用了 Z-score 做异常检测，阈值 3 对应大约 0.3% 的随机波动概率，超过就标记异常。这个逻辑放在工具层，Agent 只负责调用和决策，职责清晰。

最后是agent/report_agent.py的主编排：

import yaml from tools import db_tool, llm_tool, notify_tool, chart_tool def load_config(path="config/harness.yaml"): with open(path) as f: return yaml.safe_load(f) def run(): cfg = load_config() df, date_range = db_tool.pull_all() issues = db_tool.validate(df) if any(i["type"] == "missing" for i in issues): notify_tool.push(f"【报表异常】{issues[0]['msg']}", []) return charts = chart_tool.render(df, date_range) summary = f"新增用户 {df['new_user_count'].sum()}，交易额 {df['pay_amount'].sum():.2f}，平均ROI {df['roi'].mean():.2f}" analysis = llm_tool.analyze(summary, issues) notify_tool.push(analysis, charts) if __name__ == "__main__": run()

这套结构跑起来之后，Harness 负责调度和重试，Agent 负责业务逻辑，工具层负责具体能力。三者解耦，改哪一层都不影响其他层。

4. 用样例数据跑通端到端报表验证

配置写完了，接下来用一组样例数据验证整条链路。这一步很重要，因为很多问题只有在真实数据流里才会暴露，比如字段类型不匹配、时区错乱、模型返回格式不对。

先造一份样例数据。建一张测试表：

CREATE TABLE dws_business_daily ( dt DATE PRIMARY KEY, new_user_count INT, dau INT, order_count INT, pay_amount DECIMAL(12,2), roi DECIMAL(6,2) ); INSERT INTO dws_business_daily VALUES ('2025-01-06', 1200, 45000, 3200, 186000.00, 2.35), ('2025-01-07', 1350, 46200, 3350, 195000.00, 2.41), ('2025-01-08', 1280, 45800, 3280, 190500.00, 2.38), ('2025-01-09', 1420, 47100, 3420, 201000.00, 2.45), ('2025-01-10', 1380, 46900, 3390, 198500.00, 2.42), ('2025-01-11', 1500, 48500, 3600, 215000.00, 2.52), ('2025-01-12', 980, 41000, 2400, 132000.00, 1.68);

最后一天的数据故意做低，用来触发异常检测。跑一遍 Agent：

python main.py

预期输出分几步。第一步拉取数据，打印时间范围。第二步校验，应该检测到new_user_count、pay_amount、roi三个指标异常，因为最后一天明显偏低。第三步生成图表，在本地生成 PNG 文件。第四步调 TaoToken 生成分析，返回一段中文解读。第五步推送飞书。

如果一切正常，飞书群里会收到一条带图表的消息，分析里会提到「最后一天新增用户和交易额出现明显下滑，可能原因包括……」。

验证模型调用是否走通，可以单独测一下：

curl https://taotoken.net/api/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "用一句话说明什么是Z-score异常检测"}] }'

返回里能看到choices[0].message.content就是模型输出。这一步能通，说明 Base URL、Key、模型 ID 三件套配置正确。

端到端跑通之后，建议把 Harness 的调度接上。如果你用的是本地 cron，可以这样：

0 8 * * 1 cd /path/to/report-harness && /usr/bin/python main.py >> logs/run.log 2>&1

如果用的是更完整的 Harness 平台，把config/harness.yaml导入，配置好 runner 和密钥，就能实现托管调度、失败重试、运行历史查看。

验证阶段还要关注一个指标：整条链路耗时。样例数据量小，通常 10 秒内能跑完，其中模型调用占大头。如果耗时超过 1 分钟，检查是不是数据拉取用了全表扫描，或者模型返回太慢。

5. 常见调用失败排查：401、local proxy failed、reading choices、OAuth

跑通之后，真正上线还会遇到各种报错。这一节把最常见的几类列出来，对照排查。

401 Unauthorized。这个最直接，Key 不对或者没带上。检查.env里TAOTOKEN_API_KEY是不是完整复制了，有没有多余空格。如果用的是 Harness 平台的密钥管理，确认密钥有没有正确注入到运行环境。还有一种情况是 Key 被禁用或额度用完，去 https://taotoken.net/api-keys 看一下状态。

local proxy failed。这个报错通常出现在网络层，意思是请求没能到达目标地址。先确认TAOTOKEN_BASE_URL写的是https://taotoken.net/api，不要多加路径或者斜杠。然后检查运行环境能不能正常访问外网，如果是公司内网，确认出口策略有没有放行。注意不要用任何非官方的网络工具，直接用标准 HTTPS 请求即可。

reading choices 报错。典型信息是KeyError: 'choices'或者list index out of range。这说明返回的 JSON 结构里没有choices字段，通常是模型 ID 写错了，或者请求体格式不对。检查TAOTOKEN_MODEL是不是在可用列表里，请求的messages字段是不是标准格式。还有一种可能是返回了错误信息但被当成正常响应解析，建议在代码里加一层判断：

resp = client.chat.completions.create(...) if not resp.choices: raise RuntimeError(f"模型返回异常: {resp}")

OAuth 相关报错。如果你用的是 Claude Code 或者某些需要 OAuth 授权的客户端，可能会遇到 token 过期或者授权失败。这类客户端接入 TaoToken 时，Base URL 填https://taotoken.net/api，Key 用 API Key 而不是 OAuth token。如果客户端强制走 OAuth 流程，参考 https://taotoken.net/doc 里的接入说明，通常需要在配置里显式指定 API Key 模式。

Codex auth.json 配置。如果你用 Codex 类工具，认证信息在~/.codex/auth.json。接入 TaoToken 时，这个文件里要写全三件套：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的key", "model": "claude-sonnet-4-20250514" }

三个字段缺一不可，少一个就会报认证失败或者模型找不到。

Cline MCP 配置。Cline 通过 MCP 接工具时，模型接入部分同样要配全 Base URL、Key、Model ID。在 Cline 的设置里找到 API Provider，选 OpenAI Compatible，然后填：

Base URL: https://taotoken.net/api API Key: sk-你的key Model ID: claude-sonnet-4-20250514

CC Switch 配置。CC Switch 用来切换不同的模型配置，每个 profile 里同样要写全三件套。切换之后如果报错，先确认当前激活的 profile 是不是目标配置，再看 Key 有没有过期。

排查的时候有个通用思路：先单独测模型调用（用 curl），再测工具层（单独跑llm_tool.analyze），最后测整条 Harness。这样能快速定位问题出在哪一层。日志一定要打全，把请求的 URL、模型 ID、返回状态码都记下来，比盲目猜要快得多。

6. 把 Harness 用起来：从能跑到好用

跑通端到端只是第一步，真正让 Harness 产生价值的是把它变成日常依赖。这里分享几个实践中的经验。

第一，把模型调用成本控制住。不是每次跑报表都需要调大模型，只有检测到异常指标时才触发分析。正常周报只推数据和图表，这样模型调用量能降一个数量级。在 Harness 配置里可以用条件步骤实现：

- id: llm_analysis tool: llm_tool.analyze depends_on: [validate_data] condition: "len(issues) > 0"

第二，数据口径对齐要做成显式校验。很多报表出错不是技术问题，是口径问题。在validate里加一步，把核心指标和现有 BI 平台的值做对比，偏差超过 1% 就告警。这样能在推送之前发现问题，而不是等业务方来问。

第三，日志和运行历史要留全。Harness 的每一步输入输出、耗时、报错都存下来，出问题能回溯。建议按周分目录存，比如logs/2025-W03/，方便查找。

第四，灰度上线。先发给一两个业务方试用，确认数据没问题再全量推送。自动化报表一旦出错，影响面比手工报表大，因为没人会逐条核对。

第五，定期复盘指标。每个月看一次哪些指标没人看、哪些指标业务方经常问，该删的删，该加的加。报表不是越多越好，精准才有价值。

如果你想把模型调用这一层再简化，TaoToken 的 Coding Plan 适合长期跑 Agent 的场景，https://taotoken.net/coding-plan 里有详细说明。需要看模型对话效果可以直接在 https://taotoken.net/chat 里试。接入文档在 https://taotoken.net/doc，API Key 管理在 https://taotoken.net/api-keys，控制台在 https://taotoken.net/console。

整套 Harness 搭下来，最花时间的不是写代码，而是把数据口径和异常规则理清楚。代码部分照着上面的配置复制，一两个小时能跑通。真正让报表 Agent 稳定运行的，是那些看起来不起眼的校验、重试、告警逻辑。把这些做扎实，你就能从每周重复的报表劳动里彻底解放出来。