fix(external-evidence): clarify JSON file inputs and diagnostics

[loopx-agent]

Callers passing inline JSON to --provider-inventory-json received the same generic error as an unreadable or malformed file, and default Markdown output omitted the reason entirely. This makes every external-evidence JSON file option explicit in help, separates file-read/JSON-parse/object-shape diagnostics, and preserves the reason in JSON and Markdown without echoing supplied paths or contents.

The existing file-only input, size limit, provider lifecycle and TypeScript admission owner stay intact. The capability usage guide and reusable self-repair pattern describe the recovery.

Validation:

• 33 CLI tests passed, including all seven help routes, malformed/missing/inline inputs, same-file recovery, UTF-8/UTF-16 and canonical plan identity.
• Changed Python Ruff checks, git diff --check, semantic advisory and four-file public boundary scan passed.
• Built and installed an isolated wheel from this exact commit; 1,694 package files matched. Four real installed-CLI calls verified JSON rejection, default Markdown diagnostics, file recovery and matching plan identity with the preserved default CLI.
• The first clean wheel build lacked generated Chat assets; canonical npm ci / build:chat completed and the wheel build recovered. Default installation remains unchanged; this does not qualify provider execution, served App/Lark identity or downstream utility.

[loopx-agent]

Reviewer: model_agent; model=gpt-6.1-sol; provider=OpenAI; runtime_reported; reasoning_effort=xhigh

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

Exact head: 2ed09d13d48526c4e6ebfbca1ba23fe8d456c394; base: 509c38c502d3d0b4eafb01550efcdc4b5b5a1d17. 未发现阻塞性问题。

动机

向 external-evidence CLI 传文件和读取默认 Markdown 的调用者。
原帮助没有明确 JSON 选项接收文件，读取/解析/对象类型错误混在一起，默认 Markdown 还省略错误原因。 当前帮助明确 FILE；读取、JSON 解码、根对象和既有 providers-array 错误可区分，JSON 与默认 Markdown 可读回原因，修正同一路径文件后恢复同一规范化计划。
本次不新增 inline JSON、provider/readiness 或执行权限，不读取外部 provider、不写研究账本或活跃 Goal，不新增设置。
本轮没有独立重做安装 CLI 或 served App/Lark 采用、真实 provider 执行和下游研究效用；作者 wheel 与执行声明不转用作本轮证据。

合理交付是让文件输入的已有失败有可操作原因，调用者不必继续猜 inline 的 JSON 形状。库存、成功计划或 caller 回执仍不能证明真实 provider 执行/研究采用。

改动思路

在现有 IO/展示 adapter 中分开错误并补帮助；复用原 typed admission，避免新增 inline 语法、provider readiness 或 retry authority。 限定既有 CLI 文件输入与错误格式恢复；provider 执行、安装采用、App/Lark 送达和下游研究效用未由此认证。

Python 保留文件 IO 和展示；TS 才拥有请求 identity、provider admission、provenance 与 retirement。已有 file-only 输入、1,000,000-byte 上限、byte JSON decoder、root object 以及七个 handler 的调用不变；help/metavar 不增加必填参数、设置或权限。新 managed self-repair 行只是复用原 advisory table 的定位/恢复说明，不是新协议状态或自动执行门。CLI 专属传文件诊断，没有新 frontend/Lark 配置或用户操作。

已接受的 pre-change loopx/capabilities/external_research/README.md，版本 509c38c502d3d0b4eafb01550efcdc4b5b5a1d17：Contract / 合同 implemented，库存/caller receipt 与执行/采纳权威分开；Ownership and product surfaces / 归属与产品入口 implemented，复用 Python transport 与唯一 TS owner，保持既有 Markdown readback 和显式 provider/ledger authority。修改后的新使用说明不充当自己的验收来源；经验建议只采用完整用户恢复/真实 owner 视角。

具体改动

全四文件 +167/-16：CLI +28/-16、双语使用说明11行、advisory repair-pattern1行、新文件输入测试127行。没有 provider catalog、TS 语义 owner 或执行实现改动。

关键代码讲解

• loopx/capabilities/external_research/cli.py:23 _load_object：OSError 单独变成“readable JSON file path”；超过1M仍拒绝；JSON/Unicode 解码和 root dict 分别报告。没有按花括号/字符串猜 inline input，没有回显受测路径或内容。
• cli.py:97 _render：原 JSON error 字段也进入默认 Markdown；成功 readback 仍委托原 schema renderer，正常输出无差异。
• cli.py:132 register_external_evidence_commands：七入口的 FILE/help 说明文件合同；原 flag、参数和 handler 不变。
• cli.py:211 handle_external_evidence_command：完整 AST 与 B 相同，继续先校验原 canonical plan 与显式 execute 条件；JSON input 不是 provider 或写入授权。

本轮33个实际 CLI tests通过。独立相同解释器、B/H source、同字面输入的17组 CLI对照：11组完整 JSON/exit/readback Markdown 完全一致；六组 missing/inline/directory/malformed/nonobject/invalidencoding 仅明确诊断发生有意变化，原 invalid_request/exit1 和其余字段不变。新默认 Markdown 含同一原因；同一路径文件修正后恢复完全相同 ready plan。UTF8/UTF16、空 ready inventory、1M 拒绝、无 execute 授权，以及 receipt→parent reject→retire/readback 均走实际 TS owner；合成 caller receipt 不是实际执行认证，未调用 provider 或写 ledger。

对主干的风险

最强反例是诊断修复偷偷接受 inline、改 plan_id、回显私密输入或扩大执行。真实 CLI 负例/恢复、完整 paired outputs 与原强制执行 flag 覆盖这一边界；_load_receipt、inventory/connector/merge 和 handler 五个函数 AST 完全相同，TS、projection、catalog 和 public-GitHub owner 四处源字节相同。

这是有意的错误文字和默认 Markdown 行为变化，已在 PR、双语 guide/help 与 repair row 披露，不能声称旧错误输出字节不变；有效计划/默认无 opt-in discovery 和 readback 保持原合同。file/size/shape 与 typed validation 是机器义务，repair pattern 是 advice，不把它当作权限。

Ruff、开发期 advisory 后 full semantic、公开边界检查通过。原生 premerge 四 direct、十九 selected mandatory 通过，保留原 frontier maintainability advisory；实际 immutable base 与 head 完整失败输出以及 frontier/ratchet/budget 源字节相同，未修改检查或上限。无本次 manual hold，未查或等待 CI。未独立重做作者安装轮次、实际 served App/Lark/provider 与下游效用，不借其声明填证据。

小型未来整理已应用在同一 loader 的 IO/parse/shape 边界与 renderer，不加通用 JSON framework、第二决策源或新配置；专门输入恢复 tests 保持 consumer 语义，不镜像内部字段。可回退诊断与帮助，无状态转换或 receipt 重写。

我的整体评价

APPROVE 现有 CLI 恢复增量：实际错误可读，修正同一文件能继续原规范化流程，持续工作保留原 identity/admission 和拒绝条件；最短路径无需新确认。真实 provider/host/研究结果属于原有独立验收，不由源 CLI 资格或库存标签证明。本轮未升级安装或合并。

English verdict: APPROVE — 2ed09d1. Existing file-only CLI input now has distinct read/parse/object diagnostics and visible default Markdown errors.33 CLI tests and17 real B/H pairs verify unchanged canonical/lifecycle outputs, explicit diagnostic deltas, privacy in the tested file errors and same-path recovery; installed/live provider and downstream adoption remain unverified.

[mergify]

This pull request has merge conflicts with main and cannot be merged
until they are resolved. Please rebase or merge the base branch, @loopx-agent.

Choose the remote for the base repository, not an out-of-date fork.
For a fork clone, first inspect git remote -v; upstream must point
to https://github.com/loopx-project/loopx.git. If it is absent, add it
with git remote add upstream https://github.com/loopx-project/loopx.git.
Then run:

git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEAD

For a same-repository clone whose origin points to
https://github.com/loopx-project/loopx.git, use origin instead of
upstream for fetch/rebase. If you prefer merging the base, use
git merge <base-remote>/main and push normally.

Keep the DCO Signed-off-by trailer on every commit when you rebase.
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork