RiftCoach Agent

RiftCoach 是一个基于 Riot 公开赛后数据的英雄联盟复盘与训练助手。项目坚持“程序计算事实、知识库提供解释依据、模型负责组织表达、独立评测决定是否发布”的设计原则。

当前定位

当前版本包含 RiftCoach 独立领域核心、质量门控 Harness、可靠 Tool Runtime、RAG v1、受限 AgentRuntime、PostgreSQL 异步任务基座、玩家身份绑定，以及 owner-scoped Conversation/Message foundation、typed Memory、Training Plan/Progress、Memory-aware Context/terminal turns 和 owner lifecycle/ export。阶段 6 Session/Memory V1 已由 cbc7cbd / Actions 32408101770 完成最终 exact-SHA 公共闭环。 Stage 7 标准 MCP 与动态 Meta V1 已由 fac6fe0 / Actions 32484257736 完成最终公共闭环：RiftCoach 既能通过标准 MCP 调用受限 OP.GG lane-meta，也能被官方 MCP SDK 经 stdio 调用。项目没有直接合并 EchoMind 或 AGI-Saber；正式 Auth/RSO、SSE/前端、Riot+OP.GG 精确版本融合与阶段 8 恢复/Multi-Agent 仍未实现。

如果你想理解这些能力怎样一步步搭建、对应哪些源码/测试、面试时怎样准确表述，请从 学习与工程证据索引 开始。项目执行位置仍以 当前执行状态 为唯一事实源。

当前数据分工：

• Riot API：账号、对局详情与时间线事实；
• MatchAnalyzer：补刀、经济、伤害、视野、参团率与死亡时间等确定性指标；
• Data Dragon：英雄、装备、符文和召唤师技能的官方静态中文映射；
• OP.GG MCP：受限 lane-meta 当前快照，固定 partial provenance，不覆盖 Riot 官方事实；
• 本地 RAG v1：混合召回、来源过滤、引用证据、拒答和独立保留集门禁；
• 智谱 GLM：依据事实与检索证据生成教练式中文报告；
• 独立评测：检查数字忠实度、证据边界与过度推断，并支持受限修订和再评测。

领域输出使用版本化的 Player Summary Schema v1.0。短局会保留明细但不计入聚合，Timeline 缺失会显式记录状态而不会被伪装成零事件。

当前链路

Riot ID
→ 最近对局与时间线
→ 确定性指标汇总
→ Data Dragon 静态映射
→ Markdown 统计报告
→ 本地知识检索
→ GLM 教练式草稿
→ 独立事实评测
→ 受限修订与再评测
→ 通过后发布

项目边界

RiftCoach 只分析已经结束的公开赛后数据，不提供实时对局辅助，不读取客户端内存，不追踪隐藏敌方信息，也不自动操作游戏。

动态 Meta 已通过标准 MCP 接入受限 OP.GG lane-meta 当前快照，并以 partial provenance 与 Riot 玩家事实 严格分层。精确 patch/source freshness、全部 OP.GG 工具，以及 Riot 官方版本/静态/patch 与 OP.GG 的 多源 join 尚未实现。

本地开发

要求 Python 3.11 或更高版本。

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

复制 .env.example 为 .env，填写本地 Riot API 与智谱 GLM 配置。不要提交 .env。

当前异步 HTTP / Task 基座（阶段 6A）

仓库现在包含一个显式依赖注入的 FastAPI Adapter：app.api.main:create_app(...)，以及 PostgreSQL durable task、owner-scoped 查询、POST 202 入队、独立 polling Worker 的控制面合同。 HTTP 层不直接选择 Skill、拼 Prompt 或调用 Provider。6A-6 已为这个基座补齐默认关闭 CORS、 日志/Secret 脱敏、有限容量、terminal delete 的隐藏与补偿、retention 和安全指标。6A-7 又完成 API+Worker+PostgreSQL packaging、真实 Worker composition 和 no-I/O Linux smoke；提交 adf53e5 / Actions 32146760003 的 pytest、真实 PostgreSQL 与 Linux packaging 三个 job 已完成 exact-SHA 公共验证。

这些能力仍不等于正式公网鉴权/HTTPS、SSE 或自动 lease/reclaim。Session/Memory V1 已在后续 6B 闭环， 但真实外部 Worker 组合与 Docker/Compose 控制面已通过公共 CI，但仍不能称为正式公网部署；PostgreSQL job 继续是 task 并发与生命周期语义的阻塞证据，Linux smoke 也不证明模型报告质量。

当前 Player Link 纵向切片（6B-1 / 6B-2）

仓库还包含 POST /player-links 与 GET /player-links/{link_task_id}。POST 只把外服 Riot ID、routing region 和关系角色作为持久化 intent 入队并快速返回；独立 Player Link Worker 才会在数据库事务外调用 Account-V1，随后用一个 PostgreSQL 短事务收敛稳定 PUUID subject、当前 Riot ID alias、owner relationship 和 Link terminal。API 响应不会返回完整 PUUID，查询始终受 trusted owner 作用域限制。

先做不调用 Riot API 的 composition 检查：

python -m scripts.run_player_link_worker --worker-id player-link-worker-1 --check

只学习 Player Link 时，填入本地 RIOT_API_KEY 后可显式只启动 API 与 Link Worker，避免同时启动需要 模型 Provider 配置的 review Worker：

docker compose --profile runtime up --build api player-link-worker

若改用 docker compose --profile runtime up --build 启动完整 runtime profile，还必须同时配置当前 LLM Provider/Model/Key；后文的完整 review Worker preflight 仍然适用。服务 ready 后，可在本机固定开发 owner 下创建绑定 intent：

$body = @{
  riot_id = "<GAME_NAME>#<TAG_LINE>"
  routing_region = "asia"
  relationship_role = "self"
} | ConvertTo-Json

$link = Invoke-RestMethod `
  -Method Post `
  -Uri http://localhost:8000/player-links `
  -ContentType application/json `
  -Body $body

Invoke-RestMethod `
  -Method Get `
  -Uri ("http://localhost:8000" + $link.link)

这里只能证明 Riot ID 能解析为一个外服 PUUID；relationship_role=self 是 owner 的声明，不是 Riot 账号控制权证明。当前没有正式 Auth/RSO，因此不能创建 rso_verified，也不能把本地 fixed owner 配置冒充公网多用户鉴权。

当 Link 查询已经是 succeeded 时，可以用返回的 relationship_id 创建固定玩家主体的 Conversation， 再追加第一条 user Message。公共请求没有 owner、PUUID、subject、role 或 source 字段：

$linkState = Invoke-RestMethod `
  -Method Get `
  -Uri ("http://localhost:8000" + $link.link)

$conversationBody = @{
  relationship_id = $linkState.relationship_id
} | ConvertTo-Json

$conversation = Invoke-RestMethod `
  -Method Post `
  -Uri http://localhost:8000/conversations `
  -Headers @{ "Idempotency-Key" = "local-conversation-1" } `
  -ContentType application/json `
  -Body $conversationBody

Invoke-RestMethod `
  -Method Post `
  -Uri ("http://localhost:8000/conversations/{0}/messages" -f `
    $conversation.conversation_id) `
  -ContentType application/json `
  -Body (@{ content = "请复盘我最近的状态" } | ConvertTo-Json)

Conversation/Message foundation 本身不会因追加消息自动触发 Agent。后续 6B-4 至 6B-9 已在独立接口上 完成 Conversation-bound Review identity、Memory Candidate 写入门和 typed Preference/Profile/Review Memory、Training Plan/Progress、Memory-aware Context、terminal Assistant 与 lifecycle/export。terminal Assistant 仍只在可信 succeeded Task、publication 与 final Artifact 全部匹配时由内部 writer 追加，不能由 客户端直接伪造。

当前 Session / typed Memory 纵向切片（6B-3 至 6B-9）

长期写入采用两层模型：Candidate 保存来源、权限、确认和审计；通过 accept 后，typed materializer 才在 同一 PostgreSQL 事务中写入 Preference、Player Profile 或 Review Memory，并用 expected-version、 supersede chain、advisory lock、partial unique 和 trigger 防止静默覆盖。只读查询入口为：

GET /memory/preferences
GET /memory/players/{relationship_id}/profile
GET /memory/players/{relationship_id}/reviews
GET /memory/players/{relationship_id}/training-plan
GET /memory/players/{relationship_id}/training-progress
GET /owner-data/export
POST /owner-data/deletions
POST /owner-data/deletions/{marker_id}/retry

6B-6 typed Memory 由 5531c81 / Actions 32387026797 公共闭环；6B-7 Plan/Progress 为 f6d8922/32397290175，6B-8 Context/terminal turns 为 aacc11a/32403187972。6B-9 最终 cbc7cbd/32408101770 的公共 pytest 为 1490 passed, 116 skipped, 1 warning, 110 subtests passed， 真实 PostgreSQL 为 164 passed, 1 warning；Linux package schema 1.6 执行 bounded export、 conversation-only delete 和 Preference/Plan 存续断言，外部 Riot/Provider 调用为 0。这仍不等于账号所有权 已验证、备份副本已擦除、公网鉴权/部署或真实模型质量已经完成。

本地 Linux package 与进程职责

Dockerfile 只包含运行所需的 Python 应用、migration、Skill、Prompt Program、RAG 文档和两个启动脚本， 使用非 root 用户运行；.env、本地 cache/run、测试、报告和实验资产不会进入镜像。Compose 的启动依赖是：

PostgreSQL healthy
→ migrate 一次性升级到 Alembic head
→ FastAPI ready
→ production Worker 或 no-I/O smoke

先运行不需要 Riot/模型 Key 的 Linux 控制面 smoke：

docker compose --project-name riftcoach-packaging-smoke `
  --profile smoke up --build --detach --wait --wait-timeout 120 api
docker compose --project-name riftcoach-packaging-smoke `
  --profile smoke run --rm --no-deps smoke
docker compose --project-name riftcoach-packaging-smoke `
  --profile smoke down -v --remove-orphans

这个 smoke 会通过 HTTP 创建一条合成 task，由独立诊断 Worker 真实 claim，并故意在不访问 Riot/Provider 的前提下写入安全的 failed/worker_execution_failed；随后以 Fake Account Resolver 完成 Player Link， 再用该 relationship 创建 Conversation、追加并复读第 1 条 user Message。它证明 package、migration、API、 PostgreSQL、claim、终态回写和 Conversation/Message 接线；不证明 Coach 报告质量或真实 Riot/Provider。 成功的 Application/Runtime/Harness/Artifact 链由离线产品纵向测试单独证明。固定的 Compose project name 会把 smoke 的网络和数据卷与普通本地运行隔离；脚本本身也只接受 Compose/本机 API 与 PostgreSQL host。 不要省略 project name，否则诊断 Worker 可能接触同一 Compose project 中已有的 queued task。

运行真实本地 Worker 前，先在 .env 填入 Riot 与当前 Zhipu 产品基线配置，再执行完整预检：

python -m scripts.run_review_worker --worker-id worker-1 --check
docker compose --profile runtime up --build

--check 会验证数据库连接与 Alembic head、Data Dragon、本地 RAG、Skill/Prompt drift、Riot/Provider 配置与构造合同、Artifact 目录，然后在 claim 前退出；它不会额外付费调用模型，也不把“构造成功”冒充 Riot/Provider 凭据或领域质量已经在线验证。缺任一配置只返回 allowlisted 安全码，不会把 queued task 提前变成 running。 当前 Compose 使用显式 local fixed owner，仅供本机演示；它不是公网 Auth。不要把端口 8000 直接暴露到公网。

构建近期对局汇总：

python scripts\build_player_summary.py --riot-id "<GAME_NAME>#<TAG_LINE>" --count 10 --queue 420

生成确定性报告和 Coach 草稿：

python scripts\generate_markdown_report.py --input data\cache\player_summary_<GAME_NAME>_<TAG_LINE>.json
python scripts\generate_llm_coach_report.py --summary data\cache\player_summary_<GAME_NAME>_<TAG_LINE>.json --rag-top-k 5

执行评测与受限修订：

python scripts\evaluate_coach_report.py --summary data\cache\player_summary_<GAME_NAME>_<TAG_LINE>.json
python scripts\revise_coach_report.py --report reports\riftcoach_coach_report_<GAME_NAME>_<TAG_LINE>.md

Harness v1 单入口

阶段 2 将原先需要人工串联的“检索、生成、评测、受限修订、再评测、发布”组织为确定性状态机。Harness 负责执行顺序、修订预算、Artifact 留存和发布门控；模型只能产生候选内容，不能自行决定报告是否发布。

先使用 --dry-run 验证本地闭环。该模式会执行真实的 Summary 校验、本地 RAG、状态机、文件型 Run Store、哈希登记和发布过程，但使用确定性 Fake 替代收费的模型生成、评测和修订调用：

python scripts\run_review_harness.py `
  --summary data\cache\player_summary_<GAME_NAME>_<TAG_LINE>.json `
  --deterministic-report reports\riftcoach_report_<GAME_NAME>_<TAG_LINE>.md `
  --run-id local_dry_run `
  --dry-run

确认 dry-run 后，移除 --dry-run 执行真实 GLM 质量闭环：

python scripts\run_review_harness.py `
  --summary data\cache\player_summary_<GAME_NAME>_<TAG_LINE>.json `
  --deterministic-report reports\riftcoach_report_<GAME_NAME>_<TAG_LINE>.md `
  --publish-score-threshold 85 `
  --max-revisions 1

每次运行默认写入 data/runs/<run_id>/，其中保存输入、RAG 证据、草稿、每轮评测、修订稿、最终报告和带 SHA-256 的 manifest.json。未通过质量门控的 Coach 草稿不会成为最终报告；失败时默认发布确定性报告并标记为 degraded，也可以通过 --no-deterministic-fallback 改为拒绝发布。

阶段 3 已为模型、RAG、Riot API 和 Data Dragon 建立统一的 Provider / Tool 契约与适配器。Harness 的生成、评测和修订不再访问具体 SDK 的 choices 结构，而是统一调用 llm.chat；检索统一调用 knowledge.search。Runtime 负责 Schema、有限重试、缓存、三态熔断、fallback 和运行指标，Harness 继续只负责任务级状态与发布门控。现有数据构建脚本暂时保持兼容，后续入口可以逐步改用已经注册的 Riot API 与 Data Dragon 工具。

不需要真实玩家数据或模型密钥的完整合成示例：

python scripts\run_review_harness.py `
  --summary examples\fixtures\player_summary_demo.json `
  --deterministic-report examples\fixtures\deterministic_report_demo.md `
  --run-id harness_v1_demo `
  --dry-run

状态机、Artifact 目录、故障降级和表述边界详见 Harness v1 使用与原理。Provider、Tool Runti