mashang-service

Imported from zhangzihaoDT/mashang-service (AGENTS.md). Install upstream with npx skills add zhangzihaoDT/mashang-service. Copyright stays with the author.

AGENTS.md — mashang Service Guide

启动位置与宿主层

OpenCode 应从仓库根目录启动。 根目录是所有 Agent 命令、Makefile、MCP 配置的统一执行入口。

mashang-service 根目录是 Agent Harness / service 宿主层，承载以下能力：

• Makefile / pyproject.toml — 构建与调度
• .opencode/、opencode.jsonc、MCP 配置 — OpenCode / MCP 能力
• .env / .venv/ — 本地环境
• dataset/ — 共享数据入口
• shared/ — 共享 operator/schema
• 根 AGENTS.md / README.md — 项目级文档

Agent 工作边界：启动在根目录，工作在 mashang_workspace/。

项目定位

mashang-service 是一个汽车业务数据分析项目，包含以下分支 / 模块：

旧 mashang_runtime/（legacy frozen Runtime）与 mashang_runtime_v2/（NL 问数 Runtime）均已退役移除： 运行时系统由 Hub（Control Plane）+ Worker（Execution Gateway）+ OpenCode 共同组成； service 侧只保留「业务能力 + 确定性 Job Contract」，即 mashang_workspace/ + research_apps/ + jobs/。

共享底座：

• dataset/ — 原始数据
• .env — 环境变量
• .venv/ — Python 虚拟环境
• requirements.txt — 依赖
• shared/ — 共享 operator/schema

核心数据集：

• dataset/order_data.parquet — 订单主表（含锁单、交付、开票、退订等时间戳）
• dataset/assign_data.csv — 下发线索表（含渠道拆解、7/30日转化）
• dataset/config_attribute.parquet — 选配属性表（配置渗透率分析）

工作原则

1. 新分析能力：优先进入 mashang_workspace/
2. 运行时分层：旧 mashang_runtime/（legacy frozen）与 mashang_runtime_v2/（NL 问数）均已退役移除。运行时系统 = Hub（Control Plane）+ Worker（Execution Gateway）+ OpenCode；service 侧只保留业务能力 + 确定性 jobs/ contract。operators/schema 的 canonical 位置是 shared/。
3. 不要移动 dataset/ .env .venv/
4. 不要在 jobs/ 中做临时分析（jobs 只承接确定性执行契约）
5. 不要在 workspace 中引入破坏 jobs/ 契约的改动
6. mashang_workspace 是日常唯一主工作区
7. OpenCode 应优先读取 mashang_workspace/AGENTS.md
8. 不要在根目录创建新的 docs/scripts/eval/tests/utils
9. 新分析能力优先沉淀到 mashang_workspace/business_scripts/ + research_scripts/ + docs/ + eval/
10. 验证范围必须与改动范围匹配：改动后先 make verify-scope 解析本次改动的最小验证范围，再 make verify 执行。scope 外失败不算本次回归；扩大范围必须显式（make verify-all / --include），不得把「充分验证」等价成「跑全量 pytest / make ci」。契约见 .opencode/verification/README.md。
11. 能力产品化路径：workspace 中验证稳定的能力先成为 business_scripts，供 Hub 经 jobs/ 确定性调度；不要绕过 workspace 直接在 jobs/ 或 Research Application 中重复实现业务分析逻辑。
12. shared/ 边界：共享 operator/schema 层，不应随意修改。如修改需说明影响范围，并同步相关测试。
13. MCP 边界：MCP 能力由根目录统一提供（.opencode/ / opencode.jsonc），workspace 只消费能力。不得将本地 profile、cookies、API key、incoming 原始数据等提交进仓库。
14. capabilities/ 边界：Base Capabilities 是领域无关基础能力层。新基础能力先以 capabilities/ocr/ 为样板归位并自描述（接口 + provider + mock + tests + 消费方记录）；不要在 capabilities/ 中写入业务规则或领域解析逻辑。OCR 已从历史根 ocr/ 迁移至此（namespace capabilities.ocr）。
15. 能力引用口径：领域无关原语（OCR/检索/抓取/渲染/通知等）若未来复用于多个上层，优先沉淀到 capabilities/，而非内嵌在各 Research Application / 模块中复制实现。

其余原则详见 mashang_workspace/AGENTS.md。

业务分析工作原则

1. 优先阅读 docs：mashang_workspace/docs/ 目录下的文档是首要参考资料，包含业务术语、指标口径、车型映射、时间规则、分析范式、追问规则。
2. 优先复用脚本：mashang_workspace/business_scripts/（runtime）、research_scripts/（research）、utility_scripts/（utility）已有脚本，新需求优先基于现有脚本扩展。根目录不再有 scripts/。
3. 不要随意修改原始数据：dataset/ 下的 CSV/Parquet 是原始数据，分析应使用副本或只读方式。

上市时间必须从业务定义读取：涉及"上市以来"的时间范围，必须使用 shared/schema/business_definition.json 中 time_periods.{series}.end 字段，不得从数据中取 lock_time 最小值推断。脚本优先使用 --since-launch 参数，临时分析使用 mashang_workspace/utils/business.py 的 get_launch_date()。 4. 不要编造数据：在数据无法支撑结论时，明确说明"无数据/数据不足"。 5. 所有分析结果必须说明来源：包括数据源、过滤条件、时间窗口、指标口径。 6. 临时代码放 scratch/ 或 outputs/，稳定脚本再沉淀到 mashang_workspace/{business_scripts,research_scripts,utility_scripts}/。 7. 高频能力先在 workspace 内沉淀：高频分析路径先沉淀到 mashang_workspace/business_scripts/，供 Hub 经 jobs/ 确定性调度；业务代码不复制进 jobs/。 8. 回答数据问题前，先看 docs/data_dictionary.md 和 docs/metric_definitions.md，确认字段名和口径。 9. 对标准分析问题，优先调用 mashang_workspace/{business_scripts,research_scripts,utility_scripts}/ 下已有脚本，不要重复造轮子。 10. 如果脚本缺少参数，先小范围补充 CLI 参数，不要重写脚本。 11. 如果临时分析重复出现 2 次以上，再沉淀为 workspace 稳定脚本。 12. 所有脚本在 --format json 时输出标准 Result Contract，包含 scope/result/followup_context。 13. 分析结果可通过 mashang_workspace/eval/run_numeric_eval.py 做结构校验和非负校验。

Phase 2: Script Interface & Data Contract

标准 CLI 参数

所有核心脚本至少支持 --help，并尽量支持以下通用参数：

统一输出格式

[Summary]
  一句话结论

[Scope]
  数据源:
  时间窗口:
  过滤条件:
  指标口径:

[Result]
  核心表格或关键数字

[Output]
  输出文件路径 (如果有)

数据字典

python mashang_workspace/utility_scripts/data_dictionary.py              # 终端输出
python mashang_workspace/utility_scripts/data_dictionary.py --format csv # CSV 输出
python mashang_workspace/utility_scripts/data_dictionary.py --format json # JSON 输出

Smoke Test

pytest mashang_workspace/tests/scripts -q             # 运行所有脚本 smoke test
python mashang_workspace/tests/scripts/test_script_help.py  # 验证 --help

Follow-up Eval Cases

多轮追问测试用例在 mashang_workspace/eval/cases/followup_cases.json，覆盖:

• 锁单分车型 → 追问城市分布 (时间继承 + 代指消解)
• LS6 增程/纯电 → 追问改时间窗口 (时间替换)
• LS8 分车型 → 追问加过滤条件 (条件追加)
• 分城市 → 追问改分车型 (维度切换)
• 预测锁单 → 追问释放曲线 (分析类型切换)

Phase 3: Follow-up Runner & Workflow Validation

Follow-up Eval Runner

python mashang_workspace/eval/run_followup_eval.py                     # dry-run 模式 (默认)
python mashang_workspace/eval/run_followup_eval.py --format json       # JSON 输出
python mashang_workspace/eval/run_followup_eval.py --execute           # 真实执行
python mashang_workspace/eval/run_followup_eval.py --as-of-date 2026-06-11  # 指定基准日期

Runner 功能:

1. 读取 mashang_workspace/eval/cases/followup_cases.json
2. 逐轮解析 expected_context → 推荐脚本 + CLI 参数
3. 多轮上下文继承 (时间/指标/车型/筛选条件)
4. Symbolic time_window 解析为真实日期
5. dry-run (默认) 或 execute 模式

Context → Script 映射规则

详见 mashang_workspace/docs/followup_runner_rules.md。

Eval Tests

pytest mashang_workspace/tests/eval -q               # 运行 eval 测试
pytest mashang_workspace/tests -q                    # 运行所有 workspace 测试

Phase 4: Natural Language Context Parser

Context Parser

mashang_workspace/eval/context_parser.py 将用户自然语言解析为结构化 context，支持两种模式：

# 单轮解析 CLI
python mashang_workspace/eval/parse_context_cli.py "昨天锁单数分车型"
python mashang_workspace/eval/parse_context_cli.py "那最近 7 天呢？" --previous-context '{"metric":"lock_count_share","time_window":"last_15_days","series":"LS6","group_by":"energy_type"}'

# Runner 的 parse-text 模式
python mashang_workspace/eval/run_followup_eval.py --parse-text
python mashang_workspace/eval/run_followup_eval.py --parse-text --format json --output outputs/tables/parse_result.json

Parser 支持的字段

Context Match Rate

Parse-text 模式下比较 parsed context 与 expected_context，评估解析质量。

python mashang_workspace/eval/run_followup_eval.py --parse-text --as-of-date 2026-06-11

目标: context match rate >= 80%。当前: 92.9% (13/14 turns)。

详见 mashang_workspace/docs/context_parser_rules.md 和 mashang_workspace/eval/context_parser.py。

Phase 5: Execution Result Contract & Numeric Eval

Result Contract

所有核心脚本支持 --format json 时输出统一 Result Contract：

{
  "status": "success | partial_success | error",
  "script": "mashang_workspace/business_scripts/lock_by_model.py",
  "scope": { "data_source": "...", "time_window": {...}, "filters": {...}, "metric_definition": "..." },
  "result": { "summary": "...", "metrics": {...}, "dimensions": [...], "tables": [...] },
  "artifacts": { "csv": "...", "json": "..." },
  "followup_context": { "metric": "...", "top_entities": [...], "available_dimensions": [...] },
  "warnings": [],
  "errors": []
}

已支持 Contract 的脚本 (6个):

• mashang_workspace/business_scripts/daily_lock_count.py
• mashang_workspace/business_scripts/lock_by_model.py
• mashang_workspace/business_scripts/lock_city_distribution.py
• mashang_workspace/research_scripts/cohort_forecast.py
• mashang_workspace/business_scripts/assign_conversion_analysis.py
• mashang_workspace/business_scripts/attribute_penetration_report.py

详见 mashang_workspace/docs/result_contract.md。

Numeric Eval

python mashang_workspace/eval/run_numeric_eval.py                              # 执行并校验结果
python mashang_workspace/eval/run_numeric_eval.py --format json                # JSON 输出
python mashang_workspace/eval/run_numeric_eval.py --cases mashang_workspace/eval/cases/numeric_cases.json

当前: 5/5 cases passing (100%)。

Result Reference

context_parser 支持解析 "这 75 个" → 自动继承上一轮 top_entities 中的字段值。

python mashang_workspace/eval/parse_context_cli.py "这 75 个锁单城市分布" --previous-context '{"series":"LS8","top_entities":[{"field":"series","value":"LS8","metrics":{"lock_count":75}}]}'

详见 mashang_workspace/docs/context_parser_rules.md。

追问处理规则

1. 时间继承：用户追问中省略时间窗口时，优先继承上一轮的 time.start / time.end。
2. 指标继承：用户追问中省略指标时，优先继承上一轮的 metric / analysis_intent。
3. 代指消解：
   • "这 75 个" → 继承上一轮的过滤结果并作为新的过滤条件
   • "刚才那个车型" → 继承上一轮的 filters.series 或 filters.product_name
   • "昨天 LS8" → 继承 series=LS8 + time=昨天
4. 上下文不足时：先输出需要澄清的字段（时间、车型、指标），不要假设业务口径。
5. 口径一致：同一次 session 内保持口径一致，除非用户主动要求变更。
6. 追问→脚本映射：根据继承的上下文选择对应脚本并传参（详见 mashang_workspace/docs/followup_runner_rules.md）。

输出规范

• 简洁结论：先给结论，再给关键数字
• 表格：优先用 Markdown 表格呈现结构化结果
• 文件输出：必要时生成 CSV/HTML/PNG 到 outputs/ 目录
  • outputs/tables/ — CSV/JSON 结构化数据
  • outputs/reports/ — HTML/Markdown 报告
  • outputs/charts/ — PNG/SVG/HTML 图表
• 口径说明：每次输出附带数据来源、过滤条件、时间窗口
• 脚本路径：如果通过 workspace 脚本执行，注明脚本路径（mashang_workspace/{business_scripts,research_scripts,utility_scripts}/...）

目录结构

mashang-service/
├── AGENTS.md              ← 本文件 (项目级 Agent 指南)
├── README.md              ← 项目主文档
├── .env                   ← 共享环境变量
├── .venv/                 ← 共享虚拟环境
├── dataset/               ← 共享原始数据
├── requirements.txt       ← 共享依赖
├── shared/        ← 共享 operator/schema（非默认工作区）
│
├── jobs/                  ← 确定性执行契约层（Hub/Worker 调用的 Research Application job）
│   └── README.md          ← jobs 说明
│
├── capabilities/          ← Base Capabilities（领域无关原语：OCR/Search/Notify/Diagram/Feishu）
│
├── research_apps/         ← Research Applications（MIIT / auto_launch / nev_apeal）
│
└── mashang_workspace/     ← Daily Business Analytics Workspace（日常业务分析工具箱）
    ├── AGENTS.md          ← Workspace Agent 指南
    ├── README.md
    ├── docs/               ← 业务文档
    ├── business_scripts/    ← business tier（可被 Hub 经 jobs/ 调度）
    ├── research_scripts/   ← research tier（预测/回测/报告）
    ├── utility_scripts/    ← utility tier（DataOps/SyncOps/生成/检查）
    ├── eval/               ← Eval 测试框架
    ├── tests/              ← Smoke test (pytest)
    ├── utils/              ← 工具模块
    └── outputs/            ← 输出文件
        ├── reports/
        ├── charts/
        └── tables/

Canonical Entry Map（入口与副作用分级）

同一能力存在多个入口时，以下为 canonical 入口；旧名作为兼容别名保留。新文档、新脚本、Agent 路由一律引用 canonical 名。

副作用等级定义：

• read-only：只读本地数据，可安全直接执行。
• local write：写本地 dataset/ 或 outputs/。
• Feishu write：写飞书多维表 / 云文档。
• Feishu card：发送飞书群卡片消息。
• 常驻：常驻进程，写日志并周期性触发上述副作用。

推送类操作（Feishu card / Feishu write）执行前必须先 --dry-run 预览，确认口径后再正式发送；stale 数据默认阻断正式推送，只有显式 ALLOW_STALE=1 / --allow-stale 才可强制发送。

小订 / 预售 / 上市入口边界（勿混用）

• “小订监控 / 预售小订” 默认指指定代际预售快照 → make presale-snapshot SERIES=<GEN>（底层 presale_metrics_to_feishu.py shim → vehicle_sales_monitor --force-phase --phase presale）。
• 唯一监控实现 = business_scripts/vehicle_sales_monitor.py：sales-monitor（按 active phase）与 presale-snapshot（--force-phase 忽略 phase）共用同一 compute/card，不再有独立预售实现。
• “当前预售/上市监控” 指当前 active 代际的 phase 监控 → make sales-monitor（底层 vehicle_sales_monitor.py，带 freshness gate；不刷新数据）。
• “数据更新并同步 <代际> 上市/小订/预售监控”（仅刷新订单表 → 计算 → 推送）→ make monitor-sync SERIES=<GEN> PHASE=<launch|presale>（DRY=1 预览；底层 order_data_to_parquet.py + vehicle_sales_monitor.py）。对应关系：上市监控→PHASE=launch，小订/预售监控→PHASE=presale。
• 指定代际已进入 launch 阶段时，sales-monitor / monitor-sync 会按 launch 口径监控，而 presale-snapshot 仍按该代际预售口径生成快照（用于上市日最终预售快照）。
• 发送指定代际快照时，输出必须标注：统计截止时间、预售窗口、当前所处阶段（presale/launch）。
• make data-pipeline / daily-data-pipeline 只刷新订单 + 下发线索，且不含销售监控；如需“数据更新 + 监控推送”一体执行：用 make daily-ops（= daily pipeline + sales-monitor），仅订单表用 make monitor-sync。
• 试驾数据 / 锁单归因等其余数据集不在 Daily pipeline 内，只在 make allupdate（全量更新 + 校验）或各自独立更新入口维护，走“更新 + 整理”路径。
• monitor-sync 仅刷新订单表（order_data），不等价于 make allupdate（全量数据集）；需要全量刷新时用 make allupdate 或 make data-refresh。
• make sales-scheduler 的 09:00 每日管道同样只刷新订单 + 下发线索（daily scope）+ 校验 + 观察同步 + 监控；key day 17–23 点仅刷新订单表。试驾 / 锁单归因不在调度器内，走 make allupdate 或独立更新入口。

Fast Reference