references/evidence-workflows.md
4.3 KB查看排版效果| 1 | # Evidence, comparison, and verification workflows |
| 2 | |
| 3 | Evidence-producing tools return the complete Evidence record directly in MCP |
| 4 | `structuredContent` and CLI JSON. Read `normalized_result` for operation data, |
| 5 | and cite `evidence_id` when another tool or your explanation needs a stable |
| 6 | reference. Preserve authority, limitations, coverage, and residual unknowns. If a result |
| 7 | is incomplete or paginated, continue only when the remaining data matters to |
| 8 | the task; do not fetch a bundle or resource merely to read a result already |
| 9 | returned inline. When complete `inspect_binary_layout` or |
| 10 | `analyze_javascript_application` Evidence is already retained, call |
| 11 | `inspect_analysis_view` for a summary, one section/symbol/module, or a stable |
| 12 | page instead of repeating the producer. |
| 13 | |
| 14 | Completed `inspect_artifact` inventory also supports a summary and |
| 15 | `view: {kind: "inventory", collection: "occurrences", logical_paths: ["package.json", "main.js"]}`. |
| 16 | Omit `logical_paths` to page all available occurrences; `[]` selects none. |
| 17 | Other inventory collections are `nodes`, `edges` and |
| 18 | `integrity_contradictions`. Keep `source_complete` separate from page exhaustion: |
| 19 | a missing match in partial source Evidence does not establish absence. Use the |
| 20 | returned parent Evidence ID for subsequent views and export before closing the |
| 21 | session when the source must survive it. |
| 22 | When `tools/list` advertises `inspect_artifact.detail`, request `"summary"` to |
| 23 | retain its complete source and receive that view immediately. Without that |
| 24 | advertised choice, keep the existing complete call. CLI inspection returns |
| 25 | portable complete Evidence; save it before projecting a selected inline view. |
| 26 | |
| 27 | Use `record_unknown` to track unresolved questions in the user's investigation |
| 28 | and name the authority or environment still required. Supply supporting and |
| 29 | contradicting evidence IDs. It updates the session registry directly. |
| 30 | Use `update_unknown` with the current revision; reread after a stale revision |
| 31 | instead of retrying blindly. Only qualifying observed evidence can verify a |
| 32 | resolution. |
| 33 | |
| 34 | Use comparisons with complete, compatible page sets when claiming equivalence |
| 35 | or absence: |
| 36 | |
| 37 | - `compare_artifacts` compares inventory pages by occurrence path, content, |
| 38 | metadata, and graph relations. |
| 39 | - `compare_functions` compares explicit function Evidence, not fuzzy |
| 40 | whole-binary matches. |
| 41 | - `compare_bundles` compares canonical bundle membership and unknown history. |
| 42 | - `find_changed_behavior` combines existing comparisons; static differences |
| 43 | remain candidates, not causal proof. |
| 44 | - `build_call_path` needs explicit function dossiers from one artifact/provider; |
| 45 | an incomplete frontier makes absence unknown. |
| 46 | - `correlate_static_and_runtime` uses explicit mappings; matching patterns are |
| 47 | hypotheses, not causality. |
| 48 | - `verify_reconstruction` evaluates a finite typed specification. A pass covers |
| 49 | only declared comparable claims, not global equivalence. |
| 50 | |
| 51 | Process captures are opt-in behavioral evidence, not a security sandbox. V3 |
| 52 | captures cannot be upgraded to V4; rerun the original scenario. Distinguish root |
| 53 | exit from descendant settlement and require freshness when the task needs it. |
| 54 | A timed-out target that must write a final report needs `finalization_ms`: REA |
| 55 | sends SIGTERM to the captured root, keeps observing, and sends SIGKILL once |
| 56 | only if the target has not exited by the end of the interval. |
| 57 | `exit.finalization.signals` lists each attempt with its delivery result; the |
| 58 | observed exit signal stays in `exit.signal`, `exit.code` is null for every |
| 59 | deadline exit, and the code of a finalizer that exited on its own is in |
| 60 | `exit.finalization.exit_code` (null on a signal exit or when no exit was |
| 61 | observed). |
| 62 | |
| 63 | Use `inspect_analysis_view` with `view: {kind: "api-surface"}` on retained |
| 64 | `inspect_web_network_capture` HAR Evidence to group observed request lines by |
| 65 | method, origin and path template. Format matches are inferences, not handler |
| 66 | identity or schemas. Group pages cite parent record ordinals; consult record |
| 67 | coverage and exclusions before claiming completeness. No requests are replayed. |
| 68 | When the connected schema advertises `include_query_parameter_names`, select |
| 69 | it in the view for distinct observed names with original record ordinals. Query |
| 70 | values are omitted; the names establish neither required parameters nor a |
| 71 | complete server schema. Keep the original parent Evidence for exact URLs. |
文件内容是平台检查时读出的文本，只供查看。平台不会运行包里的任何脚本或程序。
