Scout

Scout 执行合法的开源情报（OSINT）研究，研究对象包括个人、公司与组织，生成具备溯源支持的简报——其中每一项主张均附有来源引用、获取时间戳及直接引文。其工作方式遵循分层信息源瀑布模型：优先使用公开网页资源；其次在配额限制范围内调用注册类数据库；仅在获得明确授权的前提下，才启用付费数据库。采集范围严格限定于研究目标所必需的内容。

适用场景

• 对某个人开展研究，并构建具备来源支撑的简报
• 利用公开信息对公司开展背景调研
• 依据可验证来源，判定两个档案是否指向同一人
• 汇总关于某一主体当前所有可公开获知的信息
• 将快速查询结果扩展为可审计的完整简报

不适用场景

• 非法侵入私有系统
• 窃取凭证或绕过访问控制机制
• 隐蔽式监控
• 无依据的“人肉搜索”（doxxing）
• 非以具体人物或组织为焦点的主题性研究——请改用 Sift

责任边界

Scout 负责针对人员与组织开展合法 OSINT 研究，并输出具备溯源能力的结果。

Scout 不负责以下事项：通用主题研究（由 Sift 处理）、图像处理（Look）、知识图谱写入（Elephas）、社交图谱（Weave）、通信任务（Dispatch）。

命令

• scout.research.start —— 以主体（subject）和研究目标（goal）为参数，启动一项新的研究请求
• scout.research.expand --tier <1|2|3> —— 升级至更高层级的信息源
• scout.brief.render —— 生成最终 Markdown 格式简报，含研究发现与全部信源
• scout.brief.render_pdf —— 可选：生成 PDF 格式简报
• scout.status —— 返回当前研究状态
• scout.journal —— 为本次运行撰写日志；每次运行结束时自动调用
• scout.update —— 从 GitHub 源拉取最新版本；保留已有日志与数据

不变量（Invariants）

1. 合法性优先 —— 仅使用完全公开可访问的信息源，严禁绕过任何访问控制机制
2. 最小化采集 —— 仅收集达成研究目标所必需的数据
3. 每项主张均需溯源 —— 每一项保留结论至少关联一个信源引用，含 URL、获取时间戳及原文摘录
4. 付费信源需显式授权 —— 第三层（Tier 3）调用必须已记录有效的 PermissionGrant
5. 默认禁止 doxxing —— 非经显式许可，不得披露私人细节
6. 不确定性必须显式揭示 —— 若身份识别未完成，须在简报中清晰说明

输入契约（Input contract）

ResearchRequest 必须包含以下字段：request_id、as_of、subject（类型、姓名、别名、已知所在地、已知社交账号）、goal、constraints（time_budget_minutes、minimize_pii）。

具体 Schema 请参阅 references/scout_schemas.md。

研究工作流

1. 标准化请求与主体身份输入
2. 保守地解析可能的身份匹配项
3. 执行第一层（Tier 1）公开信源采集
4. 为每个保留的主张记录完整溯源信息
5. 汇总初步发现，并标注置信度等级
6. 仅当功能启用且确有必要时，升级至第二层（Tier 2）
7. 仅在已记录显式授权（PermissionGrant）后，方可升级至第三层（Tier 3）
8. 生成最终简报，含研究发现、不确定性说明及信源日志
9. 将请求、发现、信源及决策结果本地持久化存储
10. 对确认的实体及高置信度关系，向 ~/openclaw/db/ocas-elephas/intake/{signal_id}.signal.json 输出 Signal 文件。Signal 格式详见 spec-ocas-shared-schemas.md。每个具有足够置信度的实体或关系单独输出一个文件。
11. 通过 scout.journal 写入运行日志

当 minimize_pii=true 时，最终简报中应抑制不必要的敏感细节。

信源瀑布模型（Source waterfall）

完整层级逻辑请参阅 references/scout_source_waterfall.md。

• 第一层（Tier 1） —— 公开网页、官网、新闻报道、公开备案文件、公开社交资料等。全自动执行。
• 第二层（Tier 2） —— 受速率限制的信源、各类注册数据库、扩展数据集等。仅在启用且确有增益时调用。
• 第三层（Tier 3） —— 商业 OSINT 服务商、背景调查数据库等付费信源。必须获得显式授权后方可启用。

输出要求

Markdown 格式简报须包含以下章节：执行摘要（Executive Summary）、身份识别说明（Identity Resolution Notes）、研究发现（Findings）、风险与不确定性（Risk and Uncertainty）、信源日志（Source Log）。所有发现均须附带可验证的溯源信息。

技能间接口（Inter-skill interfaces）

Scout 向 Elephas 的 intake 目录写入 Signal 文件：~/openclaw/db/ocas-elephas/intake/{signal_id}.signal.json

研究过程中每发现一个已确认的实体或高置信度关系，即输出一个 Signal 文件。Signal 格式详见 spec-ocas-shared-schemas.md。是否纳入 Chronicle 由 Elephas 决定。

Signal 文件格式详见 spec-ocas-interfaces.md。

存储结构

~/openclaw/data/ocas-scout/
  config.json
  requests.jsonl
  sources.jsonl
  findings.jsonl
  decisions.jsonl
  briefs/
  reports/

~/openclaw/journals/ocas-scout/
  YYYY-MM-DD/
    {run_id}.json

默认 config.json 内容如下：

{
  "skill_id": "ocas-scout",
  "skill_version": "2.3.0",
  "config_version": "1",
  "created_at": "",
  "updated_at": "",
  "waterfall": {
    "enabled_tiers": [1, 2]
  },
  "paid_sources": {
    "enabled": false
  },
  "brief": {
    "format": "markdown"
  },
  "retention": {
    "days": 90,
    "max_records": 10000
  }
}

OKR 指标

所有运行均适用 spec-ocas-journal.md 中定义的通用 OKR。

skill_okrs:
  - name: verified_claim_ratio
    metric: 至少含一个已验证信源引用的发现项占比
    direction: maximize
    target: 0.70
    evaluation_window: 30_runs
  - name: entity_resolution_accuracy
    metric: 身份识别结果被确认为正确的占比
    direction: maximize
    target: 0.90
    evaluation_window: 30_runs
  - name: source_diversity
    metric: 每份简报中平均唯一信源域名数量（中位数）
    direction: maximize
    target: 6
    evaluation_window: 30_runs

可选技能协作

• Weave —— 只读访问社交图谱，辅助身份上下文理解
• Elephas —— 可选：输出 Signal 文件供 Chronicle 提升使用
• Sift —— 研究过程中可调用 Sift 执行网页搜索

日志输出类型

• 观测日志（Observation Journal） —— 记录产生有效发现的研究运行
• 研究日志（Research Journal） —— 结构化的多信源联合研究会话

可见性

public

初始化

首次调用任意 Scout 命令时，自动执行 scout.init：

1. 创建 ~/openclaw/data/ocas-scout/ 及其全部子目录（briefs/、reports/）
2. 若 config.json 缺失，则按 ConfigBase 字段写入默认配置
3. 创建空 JSONL 文件：requests.jsonl、sources.jsonl、findings.jsonl、decisions.jsonl
4. 创建 ~/openclaw/journals/ocas-scout/
5. 确保 ~/openclaw/db/ocas-elephas/intake/ 目录存在（如不存在则创建）
6. 若尚未注册，则添加 cron 任务 scout:update（先执行 openclaw cron list 检查）
7. 将本次初始化操作作为 DecisionRecord 写入 decisions.jsonl

后台任务

openclaw cron add --name scout:update --schedule "0 0 * * *" --command "scout.update" --sessionTarget isolated --lightContext true --timezone America/Los_Angeles

自更新机制

scout.update 从本文件 frontmatter 中的 source: URL 拉取最新包。运行过程静默——仅当版本变更或发生错误时输出信息。

1. 从 frontmatter 读取 source: → 解析出 URL 中的 {owner}/{repo}
2. 从本地 skill.json 读取当前版本
3. 获取远程版本：gh api "repos/{owner}/{repo}/contents/skill.json" --jq '.content' | base64 -d | python3 -c "import sys,json;print(json.load(sys.stdin)['version'])"
4. 若远程版本与本地版本一致 → 静默退出
5. 下载并安装：

   TMPDIR=$(mktemp -d)
   gh api "repos/{owner}/{repo}/tarball/main" > "$TMPDIR/archive.tar.gz"
   mkdir "$TMPDIR/extracted"
   tar xzf "$TMPDIR/archive.tar.gz" -C "$TMPDIR/extracted" --strip-components=1
   cp -R "$TMPDIR/extracted/"* ./
   rm -rf "$TMPDIR"
   

6. 若失败 → 重试一次；若二次尝试仍失败，则报告错误并终止
7. 精确输出：I updated Scout from version {old} to {new}

支持文件映射表