empathyethicist/trace

# TRACE TRACE（Trajectory Analysis for Conversational Evidence）是一款用于分析 AI 与人类对话证据的法证软件，具备可重复的分类、基准治理和可审计的证据包导出能力。 TRACE 实现了 AI 行为轨迹取证方法论。它摄取对话记录，对系统行为与用户脆弱性进行分类，计算可重复的取证发现，并导出可用于法律、调查与专家审查的可审核证据包。 该项目旨在构建一个严肃的生产级取证工作流候选方案，而非研究演示。设计优先级包括：可重复性、可审计性以及有界托管模型风险。 ## 入门 - 执行概览：`docs/EXECUTIVE_SUMMARY.md` - 外部简要说明：`docs/PARTNER_BRIEF.md` - 采用准备度：`docs/ADOPTION_READINESS.md` - 试点评估计划：`docs/PILOT_EVALUATION.md` - 实验室运维：`docs/LAB_DEPLOYMENT_NOTES.md` - 首次运行快速入门：`docs/FIRST_10_MINUTES.md` - 安装与发布说明：`docs/INSTALL_AND_RELEASE.md` - 打包与演示：`docs/PACKAGING_AND_DEMO.md` - CI 与发布自动化：`.github/workflows/` - 托管提供者配置：`docs/HOSTED_PROVIDER_SETUP.md` - 适配器注册表：`docs/ADAPTER_REGISTRY.md` - 实时提供者加固：`docs/LIVE_PROVIDER_HARDENING.md` ## 状态 TRACE 目前是一个可运行的生产前实现，具备以下能力： - 语音转录摄取、标准化、哈希与取证链保管日志 - 分类工作流：支持确定性本地启发式规则、模拟 LLM 模式与托管提供者集成路径 - 滚动窗口状态摘要与人工审查模式 - 不当响应率、模式分布与危机失败率的相关性分析 - 双编码员导入与评分者间信度计算 - 结构化证据包导出：包含清单、验证输出、审计日志、模式版本、提示模板、分类后转录输出、Markdown 报告与 PDF 报告 - 包验证与清单签名命令 - 分离的清单签名验证 - 签名包的信任元数据 - 针对签名证书的 CA 文件校验 - 签名证书验证期间的可选基于 CRL 的吊销检查 - 验证夹具与自动化测试 更广泛生产部署的主要差距在于运维层面：更深入的解析器覆盖、更全面的对抗验证夹具，以及针对高负载托管模型执行的额外加固。详见 `docs/ROADMAP.md`。 ## 法证立场 TRACE 是为受过培训的调查员提供支持的工具，用于证据打包与决策辅助。 - TRACE **不**做出最终法证判定。 - TRACE **不**替代专家审查。 - TRACE 旨在保留来源信息、人工覆盖与可重复输出。 ## 核心能力 ### 摄取 TRACE 接受对话转录，在转换前计算源哈希，将消息标准化为内部模式，并生成可用于后续证据审查的保管记录。 当前支持的输入包括： - JSON 转录 - CSV 转录 - 纯文本格式转录 - 法庭风格纯文本转录 - AXIOM 风格 JSON 消息导出 - UFED 风格 XML 消息导出 ### 分类 TRACE 对以下内容进行分类： - **系统消息**：依据 Zhang 等人（2025）行为分类法 - **用户消息**：依据 TRACE C-SSRS 衍生的脆弱性量表 分类可通过以下方式运行： - 确定性本地启发式规则 - 用于测试的模拟托管模型模式 - 托管提供者推理 - 人工审查路径（支持接受 / 标记 / 覆盖行为） - 在分类输出中记录审查员覆盖理由 ### 相关性与报告 根据分类后的转录，TRACE 计算： - 不当响应率 - 模式分布 - 危机失败率 随后导出一个证据包，其中包含机器可读工件、Markdown 报告摘要、PDF 报告、验证元数据、签名就绪清单，以及用于检查托管提供者调整的校准摘要工件。 ## 仓库结构 ``` src/trace_forensics/ cli.py Command-line interface ingest.py Input parsing, normalization, hashing, custody logging classify.py Classification pipeline, windows, review loop heuristics.py Deterministic fallback rules llm.py Provider-backed model integration and normalization irr.py Inter-rater reliability import and computation report.py Correlation analysis and evidence package export schemas.py Classification schema definitions prompts.py Version-pinned prompt templates validation.py Validation workflow tests/ test_trace.py Automated verification validation/ companion_incident.json Reference transcript fixture reference_benign_case.json Baseline benign fixture reference_long_case.json Long-form distress fixture reference_mixed_case.json Mixed benign/harmful fixture reference_noisy_case.json Noisy real-world style fixture parsers/ Parser-format reference fixtures ``` ## 安装 ``` cd trace python3 -m venv .venv source .venv/bin/activate pip install -e . trace init --root ./trace-workspace ./scripts/demo_trace.sh ./demo-workspace ``` ## 快速启动 ### 检查安装 ``` trace version trace init --root ./trace-workspace trace config-check --provider heuristic trace config-check --provider hosted ``` ### 运行验证 ``` trace validate --reference ./validation/companion_incident.json trace validate --reference ./validation/reference_long_case.json trace validate --reference ./validation/companion_incident.json --root ./trace-workspace/validation_runs trace benchmark --validation-dir ./validation trace benchmark --validation-dir ./validation --profile mock-hosted --output-dir ./benchmark_artifacts trace benchmark --validation-dir ./validation --profile live-hosted --output-dir ./benchmark_artifacts_live trace benchmark --validation-dir ./validation --profile live-hosted --replay-dir ./replay_artifacts --replay-mode record --output-dir ./benchmark_artifacts_live trace benchmark-replay --validation-dir ./validation --profile live-hosted --replay-dir ./replay_artifacts --output-dir ./benchmark_artifacts_replay trace benchmark-compare --validation-dir ./validation --baseline-profile heuristic --candidate-profile mock-hosted --output-dir ./benchmark_comparison trace benchmark-compare --validation-dir ./validation --baseline-profile heuristic --candidate-profile live-hosted --output-dir ./benchmark_comparison_live trace benchmark-trend --history-dir ./benchmark_history --prefix benchmark_heuristic_latest trace benchmark --validation-dir ./validation --output-dir ./benchmark_artifacts --history-dir ./benchmark_history --sign-private-key ./keys/benchmark_signer.pem --sign-public-key ./keys/benchmark_signer_public.pem --signing-certificate ./keys/benchmark_signer.crt ``` ### 端到端演示 ``` trace ingest \ --input ./validation/companion_incident.json \ --format json \ --case-id DEMO-001 \ --examiner "Examiner-01" \ --root ./trace-workspace trace classify \ --case-id DEMO-001 \ --provider heuristic \ --review-mode auto \ --root ./trace-workspace trace report \ --case-id DEMO-001 \ --examiner "Examiner-01" \ --output ./trace-workspace/evidence_exports \ --root ./trace-workspace ``` ## CLI 命令 ### 初始化工作区 ``` trace init --root ./trace-workspace ``` ### 摄取 ``` trace ingest --input transcript.json --format json --case-id CASE-001 --examiner "Examiner-01" --root ./trace-workspace trace ingest --input court_transcript.txt --format court --case-id CASE-002 --examiner "Examiner-01" --root ./trace-workspace trace ingest --input axiom_messages.json --format axiom --case-id CASE-003 --examiner "Examiner-01" --root ./trace-workspace trace ingest --input ufed_messages.xml --format ufed --case-id CASE-004 --examiner "Examiner-01" --root ./trace-workspace ``` ### 分类 ``` trace classify --case-id CASE-001 --provider heuristic --root ./trace-workspace trace classify --case-id CASE-001 --provider mock --model mock-model --window-size 4 --root ./trace-workspace trace classify --case-id CASE-001 --provider hosted --model provider-default --root ./trace-workspace trace classify --case-id CASE-001 --provider hosted --model provider-default --replay-dir ./trace-workspace/replay_artifacts --replay-mode record --root ./trace-workspace trace classify --case-id CASE-001 --provider hosted --model provider-default --replay-dir ./trace-workspace/replay_artifacts --replay-mode replay-only --root ./trace-workspace trace classify --case-id CASE-001 --manual --root ./trace-workspace ``` ### 托管提供者配置 TRACE 的托管集成接口如下： - `TRACE_HOSTED_API_KEY` - `TRACE_HOSTED_BASE_URL` - `TRACE_HOSTED_MODEL`（可选） - `TRACE_HOSTED_ADAPTER`（可选，默认为 `openai-compatible`） TRACE 当前支持明确的托管适配器： - `openai-compatible` - `anthropic-messages` 最小化配置： ``` cp .env.example .env trace config-check --provider hosted trace config-check --provider hosted --hosted-adapter anthropic-messages --hosted-base-url https://provider.example/v1/messages ``` ### 评分者间信度 ``` trace irr-import --case-id CASE-001 --coder-2-file ./coder2_classified_transcript.json --root ./trace-workspace trace irr-compute --case-id CASE-001 --root ./trace-workspace ``` ### 报告导出 ``` trace report --case-id CASE-001 --examiner "Examiner-01" --output ./trace-workspace/evidence_exports --root ./trace-workspace ``` ### 包验证与签名 ``` trace verify-package --package ./evidence/CASE-001 trace sign-package --package ./evidence/CASE-001 --private-key ./keys/trace_manifest_signing.pem --public-key ./keys/trace_manifest_signing.pub.pem --signing-certificate ./keys/trace_manifest_signing.crt trace verify-signature --package ./evidence/CASE-001 --public-key ./keys/trace_manifest_signing.pub.pem --ca-file ./keys/trace_ca.pem --crl-file ./keys/trace_ca.crl ``` ### 验证 ``` trace validate --reference ./validation/companion_incident.json trace benchmark --validation-dir ./validation trace benchmark --validation-dir ./validation --profile mock-hosted --output-dir ./benchmark_artifacts trace benchmark --validation-dir ./validation --profile live-hosted --output-dir ./benchmark_artifacts_live trace benchmark --validation-dir ./validation --profile live-hosted --replay-dir ./replay_artifacts --replay-mode record --output-dir ./benchmark_artifacts_live trace benchmark-replay --validation-dir ./validation --profile live-hosted --replay-dir ./replay_artifacts --output-dir ./benchmark_artifacts_replay trace benchmark-compare --validation-dir ./validation --baseline-profile heuristic --candidate-profile mock-hosted --output-dir ./benchmark_comparison trace benchmark-history --history-dir ./benchmark_history --prefix benchmark_heuristic_latest trace benchmark-trend --history-dir ./benchmark_history --prefix benchmark_heuristic_latest ``` ## 质量与法证控制 TRACE 的设计围绕以下控制机制： - 转换前哈希 - 明确的链保管证工件 - 版本锁定模式与提示元数据 - 摄取、分类、IRR 与导出事件的审计日志 - 提供者输出不可用或格式错误时的确定性回退行为 - 双编码员支持与评分者间信度计算 - 对导出清单哈希的包验证 - 审查员覆盖理由在分类输出中的保留 - 分离签名验证用于已签名清单 - 签名者信任元数据与清单签名一同保存 - 包含用于回归测试的畸形解析夹具 - 导出报告中包含可选的审查员注释 - 报告附录包含工件检查清单与相关性快照 - 基准工件可签名并归档为历史快照 ## 项目策略 - 贡献指南：`CONTRIBUTING.md` - 安全策略：`SECURITY.md` - 产品意图：`docs/PRODUCT_GOALS.md` - 采用准备度：`docs/ADOPTION_READINESS.md` - 执行概览：`docs/EXECUTIVE_SUMMARY.md` - 合作伙伴简要说明：`docs/PARTNER_BRIEF.md` - 试点评估指南：`docs/PILOT_EVALUATION.md` - 实验室运维说明：`docs/LAB_DEPLOYMENT_NOTES.md` - 路线图：`docs/ROADMAP.md` - 验证策略：`docs/VALIDATION.md` - 基准治理：`docs/BENCHMARK_GOVERNANCE.md` - 提供者漂移策略：`docs/PROVIDER_DRIFT_POLICY.md` - 实时提供者加固说明：`docs/LIVE_PROVIDER_HARDENING.md` - 发布清单：`docs/RELEASE_CHECKLIST.md` - 发布标记：`docs/RELEASE_TAGGING.md` - 证据包规范：`docs/EVIDENCE_PACKAGE_SPEC.md` - 架构：`docs/ARCHITECTURE.md` - 威胁模型：`docs/THREAT_MODEL.md` - 示例导出工件：`examples/README.md` 该仓库还包含一个签名的 `live_hosted` 基准示例，以及一个签名的 `heuristic` 与 `live-hosted` 比较示例，供外部审查人员检查实际的提供者漂移，而不仅限于模拟托管行为。 当前的实时提供者示例提交记录了在启发式基线下的观察漂移，而非仅展示通过筛选的乐观案例。 仓库中还包含位于 `examples/benchmark_artifacts/live_hosted_hardened/` 与 `examples/benchmark_comparison_live_hosted_hardened/` 下的回放加固实时提供者示例工件，以便审查人员检查 `docs/LIVE_PROVIDER_HARDENING.md` 中所述的有界漂移状态。 位于 `examples/companion_incident_package/` 的配套证据包示例也以签名形式提交，包含 `calibration_summary.json`、`manifest.sig` 与 `trust_metadata.json`，以便审查人员直接检查包级校准与签名输出。 ## 开发说明 - 推荐使用 Python 3.11+。 - 托管模型执行可能需要 API 凭证与网络访问。 - 支持托管提供者，但托管提供者可能返回模式漂移输出；TRACE 会规范化常见偏差，并在需要时安全回退。 - `live-hosted` 基准配置需要 `TRACE_HOSTED_API_KEY` 与 `TRACE_HOSTED_BASE_URL`，默认使用 `provider-default`，除非设置了 `TRACE_HOSTED_MODEL`。 - 当前托管执行支持 `openai-compatible` 与 `anthropic-messages` 适配器协议。详见 `docs/HOSTED_PROVIDER_SETUP.md`。 - 通过 `trace classify --replay-dir ... --replay-mode record|replay-only` 可使用托管回放支持功能，以捕获一次提供者输出并在本地回放。 - 导出的报告、清单与基准工件现在保留提供者、模型与适配器元数据，供后续审查。 ## 许可证 MIT。详见 `LICENSE`。

标签：AI取证, CI/CD自动化, Mock LLM, 不当响应率, 专家评审, 危机失败率, 双编码, 发布自动化, 可审计性, 可重复分类, 可重复性, 司法审查, 哈希校验, 实时提供者加固, 实验室部署, 审计追踪, 对话取证, 快速入门, 托管LLM集成, 托管模型风险, 数字取证, 文档结构分析, 文档驱动, 有界风险, 治理基准, 法律合规, 滚动窗口摘要, 相关分析, 确定性启发式, 结构化导出, 自动化脚本, 行为轨迹分析, 证据包, 评分者间信度, 试点评估, 请求拦截, 调查分析, 适配器注册表, 逆向工具, 链式保管