External Evidence Research / 外部证据研究

external-evidence-research is LoopX's provider-neutral contract for turning a decision-bound research question into compact, auditable evidence. It unifies two provider classes without pretending they are the same implementation:

• a host method such as the external-research skill; and
• a connector provider such as an official-document search integration.

external-evidence-research 是 LoopX 面向决策的通用外部证据合同。它统一两类 provider 的调用与回执语义，但不把两者伪装成同一种实现：

• host 提供的研究方法，例如 external-research skill；
• connector provider，例如官方文档搜索连接器。

Contract / 合同

The lifecycle is:

1. discover: project method and connector inventory plus current readiness, while explicitly keeping registry presence, execution, and evidence coverage false unless separately observed;
2. plan: bind object + user activity + decision and required evidence kinds to one provider that is currently declared, installed, enabled, and ready, then content-address the normalized request, candidate inventory, selection, and execution envelope as plan_id;
3. provider execution: the selected host method or connector reads external sources under its own adapter and permission boundary;
4. receipt: require the caller-presented provider receipt to echo plan_id, reconstruct and verify the canonical plan, then record the receipt observation without treating it as provider execution attestation or claiming evidence coverage, admission, or automatic promotion;
5. admit: validate the exact request/provider identity and source-level provenance, bind the complete receipt digest, then record the parent agent's admit/reject decision;
6. downstream projection: pass only compact findings, limitations, direct references, evidence basis, dates, and content digests;
7. retire: revalidate the complete content-addressed admission, then retire rejected evidence immediately, or admitted evidence only after every admitted source reference appears in downstream readback.

生命周期为：discover 只读投影 method/connector 库存与当前 readiness，并明确区分 registry presence、真实执行和证据覆盖；plan 绑定“对象 + 用户活动 + 决策”并选择当前 真实 ready 的 provider，并用 plan_id 对规范化请求、候选库存、选择和 execution envelope 做内容寻址；provider 在自己的权限边界内执行；receipt 回传并校验 plan_id，只记录 caller 提交的回执，不把它冒充 provider 执行证明、证据覆盖、采纳或自动晋升；admit 校验请求、provider、完成时间、 完整 receipt digest 与逐来源 provenance，并记录父 Agent 的采纳/拒绝；下游只投影紧凑证据；被采纳的来源全部完成 下游读回后才可 retire，且 retirement 会先重验完整 admission identity。

The connector registry is only inventory and telemetry. A connector row marked supported is projected as ready=false until a current provider lifecycle readback proves installation, enablement, and readiness. Registration never counts as execution or evidence coverage.

Connector registry 仅拥有库存与遥测。即使 connector 标为 supported，在当前 provider 生命周期读回证明 installed/enabled/ready 之前仍投影为 ready=false。 注册不等于调用，更不等于证据覆盖。

CLI / 命令行

The external-evidence --*-json options take file paths, not inline JSON. The provider inventory file contains an object with a providers array ({"providers": [...]}), not a bare array. File-read errors, invalid JSON, and non-object roots are reported separately in JSON and default Markdown output so callers can correct the input.

external-evidence 的 --*-json 参数接收文件路径，不接收 inline JSON。 provider inventory 文件的根对象须包含 providers 数组，不是裸数组。 JSON 与默认 Markdown 输出分别报告文件读取、JSON 解析和根对象类型错误， 便于调用者修正输入。

loopx external-evidence discover \
  --connector-registry \
  --format json

loopx external-evidence plan \
  --objective "Compare current behavior" \
  --user-activity "Choose an implementation" \
  --decision "Whether to adopt it" \
  --evidence-kind current_behavior \
  --evidence-kind counterexample \
  --provider-inventory-json providers.json \
  --format json

loopx external-evidence receipt \
  --plan-json plan.json \
  --receipt-json receipt.json \
  --format json

loopx external-evidence admit \
  --plan-json plan.json \
  --receipt-json receipt.json \
  --decision admit \
  --reason "Direct source answers the decision" \
  --admit-source https://example.com/original \
  --format json

loopx external-evidence retire \
  --admission-json admission.json \
  --downstream-source https://example.com/original \
  --format json

Provider inventory is an observation, not authority. A ready provider row uses protocol external_evidence_research_v0 and carries explicit declared, installed, enabled, and ready booleans. Raw pages, transcripts, cookies, credentials, and private notes remain provider-private.

Ownership and product surfaces / 归属与产品入口

• The TypeScript contract owns request identity, provider admission, provenance validation, parent admission, compact projection, and retirement readiness.
• Python adapts the existing CLI and effect-runtime transport; it does not reimplement those decisions.
• Managed Turn callers can invoke the same effect-runtime methods: external_evidence.discover, external_evidence.plan, external_evidence.receipt, external_evidence.admit, and external_evidence.retire.
• CLI readback renders the same validated plan, source, parent decision, actual deepresearch-ledger coverage and retirement as Markdown. Existing conversation answer/report and Lark Markdown transports consume that output; no new UI configuration or evidence state machine is introduced.

TypeScript 是 discovery 真值边界、请求身份、provider 准入、provenance 校验、父 Agent 采纳、紧凑投影与 退休条件的唯一语义 owner。Python 仅适配 CLI 与 effect-runtime transport。Managed Turn 复用同一方法；CLI readback 的同源 Markdown 可由现有会话答复/报告和 Lark Markdown 运输路径展示，不新建 registry 或状态机。

Host methods and connectors / 宿主方法与 connector

Reuse the host's existing source tools: a research skill can be a method, while a GitHub, browser or search tool can be a connector. No generic crawler, MCP client or second browser controller is needed in Core. Provider-specific setup and execution remain with the upstream tool and host adapter.

先复用宿主已有读取工具：调研 skill 可以作为 method，GitHub、浏览器或搜索工具可以 作为 connector。Core 无需再实现爬虫、MCP client 或浏览器控制器；安装与执行仍归 上游工具及宿主 adapter。

1. Perform a bounded readiness probe using the real host tool. Registry supported, command presence and upstream doctor output alone are insufficient. Write an observed provider inventory using the fields above; carry a concrete unavailable reason when any lifecycle prerequisite fails.
2. Run plan --provider-inventory-json providers.json --preferred-provider-id PROVIDER_ID with the actual objective, activity and decision. Retain the caller's explicit registry/runtime options. Inspect the ready plan before executing the selected host tool.
3. Execute that tool under its own permission boundary. The CLI's bundled execute dispatches only method:public-github; it does not execute an arbitrary host method or connector. Return the following caller-authored receipt shape, copying identity fields from the saved plan:

{
  "schema_version": "loopx_external_evidence_receipt_v0",
  "plan_id": "<plan.plan_id>",
  "request_id": "<plan.request.request_id>",
  "provider_id": "<plan.selected_provider.provider_id>",
  "provider_kind": "<plan.selected_provider.provider_kind>",
  "status": "succeeded",
  "sources": [{
    "source_ref": "https://example.com/original",
    "source_family": "original-publisher",
    "basis": "observed",
    "finding": "The bounded observation that answers the request",
    "limitation": "What was not inspected or tested",
    "publication_date": null,
    "accessed_at": "<actual ISO timestamp>",
    "content_digest": "sha256:<digest of the inspected content>"
  }],
  "summary": "Compact evidence summary",
  "limitations": ["Caller receipt is not provider execution attestation"],
  "completed_at": "<actual ISO timestamp>"
}

1. Validate with receipt, then explicitly admit or reject source refs. Use readback for the same shared Markdown/JSON projection. For durable downstream use, start the existing deepresearch ledger with exactly the plan objective as its question, then run readback --admission-json admission.json --project research --execute. Check write_blockers, actual lineage coverage and retirement readiness before declaring the slice used.

实际 probe 后才能填 ready inventory；先生成 plan，再调用选中的宿主工具。上述 JSON 是 caller 回执，不是执行认证。逐来源记录原始 URL、同源关系、依据、真实日期、读取 内容 digest 与局限；用 receipt 验证，再独立采纳/拒绝。持久化沿用既有 deepresearch 账本，研究问题必须与 plan objective 完全一致；实际读回覆盖后才可退休。

For a failed or empty read, use failed or no_evidence with sources: []; do not recycle a previous successful body. Parent rejection can retire that receipt without writing a source. Other successfully inspected sources remain available through their own plans and admissions. Search snippets, extracted text and browser observations retain their actual read scope; linked pages, images, authenticated scope and broad reliability are separate qualifications.

失败/空读回用 failed/no_evidence 和空来源，不借用旧正文。父 Agent 拒绝后可退休 失败回执；其他已成功读取的来源按自己的 plan/admission 继续。摘要、抽取正文和页面 观察保留真实读取范围，不据此声称读过链接、图片或具备未测试的账户权限。

Host-provider reuse checkpoint records a bounded real method, public-scope connector and failed-reader journey.

Ego/X discovery / Ego/X 发现

Use X discovery when the question needs creator demos, current discussions or original announcements, or the user requests that platform. It is a retrieval route, not a mandatory source for every research question. Prefer official docs or source code for technical verification. The host external-research method guides that choice; the contract does not automatically run a browser or search X merely because a research plan exists.

需要作者演示、近期讨论、原始公告或用户指定 X 时，使用 X 发现路径；不是每个问题 都必须搜索 X。技术事实继续回到官方文档或源码核验。宿主 external-research 方法 指导选路；研究计划本身不会自动启动浏览器或搜索。

Reuse the optional Ego source reader's search_x when that tool is available. Otherwise use the installed ego-browser CLI under its current skill: open the platform search UI, wait for actual results, retain original post links and inspect relevant media. Web-search snippets and a search URL alone are not evidence that an Ego/X search ran. Preserve the existing TaskSpace and account boundary; do not copy cookies, install a browser, change profiles or take over user control to complete a search.

优先复用已启用 Ego reader 的 search_x；没有该工具时，按当前 Ego skill 使用已安装 CLI 打开平台搜索、等待真实结果、保留原帖链接并检查相关媒体。网页搜索摘要或仅有 搜索 URL 不证明已通过 Ego 搜索 X。沿用现有 TaskSpace 和账户边界，不复制 cookie、 安装浏览器、更换 profile 或接管用户控制。

After a bounded real readiness probe, represent this observed host tool as a connector in the existing inventory; its provider id is caller-declared, not a new built-in registration. Use plan before the selected research execution, then receipt, explicit admit/reject and readback as above. Query excerpts are discovery evidence; original-post and video reads have their own scopes. An empty platform state is different from a loading shell, login wall or failed read. Keep raw result pages and account context provider-private. No new Goal, evidence ledger, automatic admission, account mutation or background search is created by this route.

真实有界 probe 后才把宿主工具作为既有 inventory 的 connector；provider id 由调用者 声明，不新增 built-in 注册。正式执行前生成 plan，随后校验 receipt、明确采纳/拒绝并 读回。搜索摘录、原帖读取和视频观察分别记录范围；空结果、加载中、登录墙和失败不能 混为一谈。原始结果与账户上下文留私有侧，不创建新 Goal、平行账本、自动采纳、账户 写入或后台搜索。

Public GitHub method / 公开 GitHub 方法

The bundled method:public-github provider performs anonymous, bounded HTTPS GETs only. It reads UTF-8 files from explicitly selected full commit SHA URLs. No token, cookie, private repository, branch-head URL, redirect, proxy credential, raw page persistence or automatic admission is used. Repository public visibility is checked at planning and again for each execution read. A saved ready row alone cannot authorize or prove a successful read.

该内置 method 只做匿名、有界 HTTPS GET，只接受显式选择的完整 commit SHA 文件 URL。 规划和执行均检查仓库当前公开性；不使用 token、cookie、私有仓库、分支 head、重定向、 代理凭据、原文持久化或自动采纳。保留的 ready 行本身不证明执行成功。

Each successful source's accessed_at records its UTC observation after the bounded read; receipt completed_at is recorded after all attempted reads, including failures. Neither timestamp establishes publication or first availability.

每条成功来源的 accessed_at 在有界读取后记录 UTC 观察时间；回执的 completed_at 在全部读取尝试（包括失败）结束后记录。两者均不证明发布或首次可得时间。

Failure limitations identify the reached step: public repository visibility, source file read, or source text validation. HTTP status codes remain visible; exception messages, response bodies and transport reasons remain redacted. The step is diagnostic context, not proof of a timeout, missing permission or source unavailability beyond this attempt. Partial successful reads are retained.

失败局限会标明实际到达的步骤：仓库公开性核验、来源文件读取或文本验证。保留 HTTP 状态码，不暴露异常正文、响应内容或传输原因；步骤只辅助诊断，不能据此推断超时、 权限缺失或该来源永久不可用。部分成功的来源仍保留。

loopx external-evidence plan --public-github \
  --objective "Inspect public source" --user-activity "Choose a source" \
  --decision "Whether a literal is present" --evidence-kind literal_match \
  --source https://github.com/OWNER/REPO/blob/FULL_COMMIT_SHA/README.md \
  --search-term LoopX --format json > plan.json
loopx external-evidence execute --plan-json plan.json --execute --format json > execution.json
loopx external-evidence readback --plan-json plan.json --receipt-json execution.json
# The parent separately inspects findings and chooses admit/reject.
loopx external-evidence admit --plan-json plan.json --receipt-json execution.json \
  --decision admit --reason "Direct source answers this bounded decision" \
  --admit-source https://github.com/OWNER/REPO/blob/FULL_COMMIT_SHA/README.md \
  --format json > admission.json
loopx deepresearch start --project research --question "Inspect public source"
loopx external-evidence readback --plan-json plan.json --receipt-json execution.json \
  --admission-json admission.json --project research --execute --format json
loopx external-evidence readback --plan-json plan.json --receipt-json execution.json \
  --admission-json admission.json --project research

execute --execute authorizes source reads only. readback --execute authorizes writing already explicitly admitted compact sources to the existing research ledger. It requires the active research question to match the plan objective. Retries for the same admission are idempotent. Wrong questions, unrelated existing sources and exhausted source budgets remain blockers; partial projection stays retained until every admitted source is actually read back with matching lineage. Omit --execute for read-only projection; omit --public-github to avoid the provider readiness probe. There is no persistent provider enablement to uninstall. Original sources remain available on partial, empty and failed results. Literal matches prove neither semantic conclusions nor evidence completeness.

execute --execute 只授权读取来源；readback --execute 只把已明确采纳的紧凑证据 写入现有研究账本，且要求研究问题与 plan objective 相同。同一 admission 可幂等重试； 问题不匹配、已有不相关来源或预算耗尽仍为 blocker。部分下游投影保持 retained， 直至全部已采纳来源以匹配 lineage 实际回读。省略 --execute 可只读回读；省略 --public-github 不探测该 provider。没有持久开关需要卸载。部分、空或失败证据 保留原始来源退路；字面匹配不证明语义结论或证据完整性。

Real qualification (anonymous network reads, disposable synthetic ledger): uv run --extra test python examples/public-github-evidence-live-smoke.py --execute-public-provider --source https://github.com/OWNER/REPO/blob/FULL_COMMIT_SHA/README.md. Packaged conversation readback: set LOOPX_PERSONAL_WORKSPACE_PACKAGED=1 and LOOPX_PERSONAL_WORKSPACE_SCENARIO=external-evidence-readback, then run node examples/personal-workspace-browser-smoke.mjs. Live authenticated connector and Lark delivery qualification remain separate; this method grants no connector credentials or outbound-message authority.

真实验收会进行匿名网络读取并使用一次性合成账本；打包会话验收沿用上述环境变量和命令。 真实带凭据 connector 与 Lark 送达资格仍是独立边界；本方法不授予 connector 凭据或外发消息权限。