oma-market

市场研究 Agent - 社区信号情报

调度

目标

运行上游 last30days 研究引擎（始终使用最新版本，由 oma 管理）进行社区信号研究，然后结合用户意图（痛点 / 趋势 / 竞品 / 探索），通过战略框架组织研究结果，并在 .agents/results/market/ 下保存一份简报。

意图特征

• 用户询问某个产品或类别的痛点、用户投诉或客户之声信号。
• 用户询问某个领域本周或本月有哪些趋势正在兴起、增长或衰退。
• 用户询问某个产品与另一个产品在社区情绪或定位方面的比较。
• 用户希望围绕某个主题、人物、公司或股票代码进行探索性市场研究。

适用场景

• 从社区帖子中提取真实用户痛点（含真实点赞数和热门评论的 Reddit 帖子、HN、X、Bluesky、GitHub Issues）
• 检测某个类别在特定时间范围内的趋势（--days 7|30|90|180）
• 竞品情绪分析和 SWOT / 波特五力定位
• 开放式探索研究（--discover）、人物模式、招聘信号（--hiring-signals）、后续深入分析（--drill）

不适用场景

• 无市场分析框架的一般网络研究 → 直接使用 oma-search
• 学术文献 → 使用 oma-scholar
• 实时仪表板或定时监控 → 使用 oma schedule <action> 调用此技能

预期输入

• 主题字符串；可选 --intent pain|trend|competitor|discovery（否则根据 resources/intent-rules.md 分类）
• 可选时间范围（--days）、--vs <entity>（竞品）、--frameworks auto|none|swot,5f,pestel
• 任何原生 last30days 标志（参见 oma market run --help）——原样传递

预期输出

• 单份 Markdown 简报，路径为 .agents/results/market/{topic-slug}-{YYYYMMDD}.md
• 第一行：引擎徽章（🌐 last30days v{VERSION} · synced {date}）；正文遵循上游 OUTPUT CONTRACT；根据意图附加框架章节；保留引擎页脚
• 原始引擎产物保存在 market.save_dir 下（默认为 .agents/results/market/raw/）

outputs:
  - name: market-brief
    description: Single LAW-compliant markdown brief with framework sections
    artifact: ".agents/results/market/*.md"
    required: true

依赖项

• oma market resolve / oma market run — 引擎位置、Python 3.12+ 解析、--save-dir 默认值
• 解析出的引擎根目录中的上游 SKILL.md（位于 oma market resolve --json 的 skillMd）——权威研究规范
• resources/intent-rules.md、resources/frameworks/、resources/output-laws.md、resources/execution-protocol.md

控制流特性

• 首先运行 oma market detect-trap 闸门（退出码 2 = REFUSE，退出码 4 = 无效）
• 引擎始终使用最新版本：oma market resolve 会刷新托管副本（受限流控制），离线时则回退到缓存副本；设置固定的 market.path / LAST30DAYS_HOME 后将不再自动更新
• 需要密钥 / Cookie 的来源会在引擎中自动跳过；无需密钥的来源（Reddit、HN、GitHub、Polymarket、arXiv、Techmeme、Digg、web）始终运行
• 根据意图自动切换框架（痛点 / 趋势 → SWOT；竞品 → SWOT + 波特五力；探索 → SWOT + PESTEL）

结构流程

入口

1. 运行 oma market detect-trap "<topic>"。退出码为 2 → 显示 REFUSE 原因和改写建议，然后停止。
2. 运行 oma market resolve --json。若 ok: false → 报告 reason（缺少引擎 → oma market update；缺少 Python → 给出安装提示），然后停止。绝不回退到仅使用 WebSearch 的综合分析并将其作为市场研究结果呈现。
3. 从头到尾阅读 engine.skillMd 中的上游规范。内容较长是有意为之；不要略读。将 engine.root 视为其 SKILL_DIR。
4. 根据 resources/intent-rules.md 分类意图；映射到引擎标志和框架组合。

场景

1. 准备：运行 detect-trap、resolve，读取上游 SKILL.md，并分类意图。
2. 上游步骤：严格遵循上游 SKILL.md — Step 0（由用户同意驱动的首次运行设置向导）、意图解析、Step 0.45（其自身的查询质量预检）、Step 0.5 / 0.55（WebSearch 可用时解析句柄、subreddit、hashtag）、Step 0.75（查询计划）。仅跳过其中的“Runtime Preflight” Python 查找区块：oma market run 已解析好解释器。
3. 运行：凡是上游契约要求运行 "${LAST30DAYS_PYTHON}" "${SKILL_DIR}/scripts/last30days.py" <args> 的地方，都使用相同参数运行 oma market run <args>（前台运行、超时 5 分钟、--emit=compact）。除非你传入 --save-dir，否则会根据 market.save_dir 自动添加 --save-dir。
4. 综合：严格按照上游 OUTPUT CONTRACT 生成简报（首行是徽章、包含 Ranked Evidence Clusters、LAWs）。然后根据意图追加选定的框架章节，并且仅使用引擎输出中已有的聚类作为证据（resources/frameworks/）。
5. 收尾：按照 resources/output-laws.md 执行自检，将简报写入 .agents/results/market/{topic-slug}-{YYYYMMDD}.md，预览前 50 行。

转换

• --vs <entity> 或“A vs B”措辞 → 竞争者意图 → 上游 COMPARISON 流程（按其契约指定，执行两轮检索 + 正面对比）→ SWOT + Porter's 5F。
• 人物 / 公司 / 股票代码主题 → 原样应用上游人物 / 招聘信号 / StockTwits 处理方式。
• engine.status: stale → 在报告中加入 note（研究使用的是缓存的引擎版本）。

失败与恢复

• detect-trap 退出码为 2 → 拒绝；不要运行引擎；仅在用户明确再次确认后才使用 --force。
• oma market resolve 未通过 → 说明原因并停止；不要运行引擎。
• 引擎退出码非零 → 原样报告 stderr；除非上游契约规定已输出的紧凑格式内容仍然有效，否则不要根据部分 stdout 生成综合结果。
• 上游 Python 版本门槛 / 设置向导消息 → 按照上游契约的指示原样转达给用户。

退出

• 成功：生成包含徽章、聚类、框架和引擎页脚的简报；报告文件路径。
• 部分完成：引擎运行时跳过了某些来源（页脚会列出这些来源）——说明这一点；绝不可用虚构证据凑数。

逻辑操作

操作

操作	SSL 原语	证据
detect-trap 预检	VALIDATE	主题参数、陷阱模式规则
解析引擎 + Python	CALL_TOOL	oma market resolve --json
读取上游契约	READ	engine.skillMd
分类意图	SELECT	resources/intent-rules.md
上游研究前步骤	INFER	上游 SKILL.md Steps 0–0.75
运行引擎	CALL_TOOL	oma market run <args>
综合 + 框架	WRITE	上游 OUTPUT CONTRACT、resources/frameworks/
自检 + 编写简报	WRITE	resources/output-laws.md、.agents/results/market/

工具和仪器

• oma market detect-trap <topic>（预检门控）
• oma market resolve [--refresh|--offline] [--json]（解析引擎 + Python；托管最新版本）
• oma market update（强制刷新托管引擎）
• oma market run <engine args…>（透传至已解析的上游引擎 Python 入口点）

规范命令路径

TOPIC="VS Code pain points"
oma market detect-trap "$TOPIC"
oma market resolve --json            # read .engine.skillMd, then follow it
# … upstream Steps 0 / 0.45 / 0.5 / 0.55 / 0.75 …
oma market run "$TOPIC" --plan "$QUERY_PLAN_FILE" --subreddits=vscode --emit=compact --save-suffix=v3

资源范围

范围	资源目标
NETWORK	仅限引擎内部（各来源的抓取器）；GitHub 用于刷新托管引擎
LOCAL_FS	~/.cache/oma-market/last30days/<tag>/（引擎）、~/.config/last30days/（引擎配置、密钥）、.agents/results/market/（简报 + 原始数据）
PROCESS	oma market 子命令 → 已解析的上游 Python 入口点

前置条件

• 主题通过 detect-trap。
• oma market resolve 通过（引擎已就绪；在 PATH 中、通过 uv，或使用 market.python / LAST30DAYS_PYTHON 固定的版本中找到 Python ≥ 3.12）。

效果与副作用

• 将简报写入 .agents/results/market/{topic-slug}-{YYYYMMDD}.md，并将原始引擎文件写入 market.save_dir。
• 首次运行：经用户同意后，上游设置向导可能会写入 ~/.config/last30days/.env。
• 如果缺少 Python 3.12+，oma market resolve 会在上游设置向导启动前停止。转达其安装提示；在获准安装解释器后，重试解析。不要指望被跳过的上游 Python 预检会安装它。

参考资料

• 执行协议：resources/execution-protocol.md
• 意图路由：resources/intent-rules.md
• 输出规范：resources/output-laws.md
• 适用框架：resources/frameworks/swot.md、resources/frameworks/porters-5f.md 或 resources/frameworks/pestel.md（仅加载所选框架）
• 验证：resources/checklist.md
• 恢复：resources/error-playbook.md
• 上游引擎说明：从 oma market resolve --json 读取已解析的 engine.skillMd 路径；上游脚本由引擎管理，不属于打包的技能资源。