内容
# 阴影
**人工智能代理的加密证据层。** 每个会话都成为一个签名的、哈希链接的记录，您可以交给审计员。 使用单个HTML文件离线验证。 验证离线与单个HTML文件。
> *相同的线路，不同的保证。* `claude-mem` 是代理的内存。 阴影是审计员的证据。 两者都钩住同一个克劳德代码事件。 不同的工作。
<p align="center">
<img src="./docs/architecture.svg" alt="Shadow architecture: agent session → adapter → shadow-attest-core → signed bundle → CLI + verify.html + M5 replay demo, with the trust ladder shown" width="900" />
</p>
**为什么现在** — 三个外部信号在2026-07汇聚：
- **Anthropic Claude Code v2.1.205（2026-07）** 添加了防止篡改会话记录文件自动模式规则 — Anthropic本身现在将会话完整性视为首要关注点。 阴影发送了Anthropic悄悄承认的完整性收据。 [变更日志](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
- **Terry Tao公开使用编码代理重建应用程序（2026-07-11）** — 领域奖获得者祝福该类别意味着“AI编码工具是否严重？”的争论已经结束。 接下来是信任和可审计性。 [terrytao.wordpress.com](https://terrytao.wordpress.com/2026/07/11/old-and-new-apps-via-modern-coding-agents/)
- **arxiv 2606.04990 — “从代理轨迹到信任”调查** 将*执行出处 + 证据跟踪* 框架为LLM代理的新兴信任基元。 阴影发送了文献刚刚命名的类别的工作代码。 [arxiv](https://arxiv.org/html/2606.04990v1)
**第一个垂直方向**：AI辅助信用决策。 阴影签署每个决策 — 裁决、不利行动原因代码、模型清单、字典哈希 — 使用Ed25519，与SHA-256链接，允许第三方在数月后验证决策是否未被悄悄重写。 裁决引擎本身是确定性规则； LLM角色生成人类审查者的散文理由，但不能更改裁决。
**第二个垂直方向（进行中，目标2026-08-02）**：会话级证据包 via `@shadow/adapter-claude-code` — 每个Claude Code会话自动生成一个签名的包。 见 [`packages/adapter-claude-code/`](./packages/adapter-claude-code/).
**状态**：预1.0。 未审计。 不是合规产品 — 它生成的证据支持合规叙述。
**Shadow证明的内容。** Shadow证明 **完整性**：记录的事件在密封后未被悄悄重写。 它不证明 **内容真实性**：捕获时代理的行为是否良性，提示注入免费或策略合规。 绿色 `✓ Bundle verified` 表示“这是已签名的记录” — 而不是“此会话是安全的”。 v3.1路线图添加可选的注入检测标记，以便审计员可以看到哪些事件在捕获时被标记为可疑（完整性+怀疑，诚实标记 — 而不是完整性+健康证明我们无法给出）。 见 [`docs/THREAT_MODEL.md`](./docs/THREAT_MODEL.md) 一旦编写（P1）七类攻击表。
**零遥测。** Shadow不打电话回家。 没有使用情况的ping，没有崩溃报告，没有分析 — 来自库或CLI验证器。 通过grep源代码验证：`shadow-attest-core` 和 `bin/` 中的任何CLI都不打开到Shadow控制的主机的出站套接字。 安全策略： [`SECURITY.md`](./SECURITY.md).
<!-- readme-stats:begin -->
**版本**: 2.0.3
**测试**: 1504/1507通过（0失败）
**证明签名字段**: 21个参数，14个追加条件绑定
**发布标签**: 59
<!-- readme-stats:end -->
上面的数字由 `node scripts/readme-stats.mjs --write` 从源代码重新生成。 CI阻止推送到drift。
## 60秒验证演示
克隆存储库，运行验收演示，并查看篡改检测路径从头到尾触发：
```bash
git clone https://github.com/alex-jb/shadow-mentor
cd shadow-mentor && npm install
npm run demo:attestation
```
演示生成一个Ed25519密钥对，签署3个贷款决策，验证它们，然后修改一个字节并显示验证器检测到篡改。 无需外部LLM调用，无需API密钥。
### 或者从npm安装
核心基元作为 [`shadow-attest-core`](https://www.npmjs.com/package/shadow-attest-core) 发布在npm上：
```bash
npm install shadow-attest-core
```
包括M1（证据包）+ M3（外部锚点：RFC 3161 TSA + Sigstore Rekor + CA信任存储）+ M4（离线验证）截至v2.0.0（2026-07-11从操作员笔记本发布； v2.0.1+通过CI发布工作流开始提供出处签名）。
## v3证据包 — AI代理的飞行记录器
Shadow v3（进行中，目标发布2026-08-02）将每个决策的证明推广为**会话级证据包**：一个签名的、哈希链接的AI代理执行记录，可以独立离线验证。 信用决策垂直成为第一个参考实现； 相同的基元涵盖Claude Code会话、MCP工具调用或任何OpenTelemetry仪器代理。
规格： [`spec/EVIDENCE_BUNDLE.md`](./spec/EVIDENCE_BUNDLE.md) · 模式： [`spec/evidence-bundle.schema.json`](./spec/evidence-bundle.schema.json).
**今天发货（M1 + M2.3 + M4）：**
```js
import { createSession, appendEvent, sealSession, verifyBundle } from "shadow-attest-core";
const session = createSession({
agent: { name: "claude-code", version: "1.2.3" },
models: [{ model_id: "anthropic:claude-sonnet-4-6", provider: "anthropic" }],
environmentFingerprint: { os: "darwin-25.3.0", node_version: process.version },
keyId: "prod-2026-Q3",
privateKey,
});
appendEvent(session, { event_type: "user_message", actor: "user", payload: { text: "..." } });
appendEvent(session, { event_type: "tool_calls", actor: "agent", payload: { tool: "grep" } });
appendEvent(session, { event_type: "tool_result", actor: "tool", payload: { hits: 0 } });
const bundle = sealSession(session);
// bundle 已签名，链接，可离线验证
```
以三种不同的方式验证包：
- **浏览器** — 将任何 `bundle.json` 拖入 [`verify.html`](./verify.html)。 零网络，零构建步骤，从USB驱动器工作。 包括审计员工作流的匹配密钥输入/绿色-红色UI。
- **CLI** — `npm run verify:bundle -- <bundle.json> --public-key <public.pem>` （即 `node bin/shadow-verify.mjs`）。 CI友好退出代码： `0` 已验证， `1` 失败， `2` 用法， `3` I/O。
- **GitHub Actions** — [.github/actions/shadow-verify](./.github/actions/shadow-verify) 复合动作。 将其连接到PR工作流中，任何破坏链的包更改都会导致合并失败。
**v3 M1.2验收标准（全部满足）：**
- 10,000事件会话密封+验证 **69毫秒** 在M系列MacBook上（目标5秒，72倍以下）
- kill -9 会话中间留下JSONL日志， `recoverSession` + `sealPartialBundle` 变成有效的部分包
- 任何字节篡改/事件重新排序/事件删除都会导致验证失败，并带有精确的 `{failedSeq, reason}`
有效载体是内容寻址的，并与事件记录分开存储，因此GDPR擦除请求使 `payload_ref` 失效而不使链失效（`payload_hash` 保留；存储器清空）。
## 架构
两层。 见 [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) 获取详细信息。
**裁决引擎** — `lib/run-loan-council.js`，确定性。 读取贷款模式（`credit_score`，`debt_to_income`，`loan_to_value`，金额，部门）并通过命名常量阈值返回 `refuse_to_serve` / `block` / `escalate` / `approve` 之一。 此路径内无LLM调用。 给定相同输入，比特对比特可复制。
**理由层** — `lib/prompts.js` + `api/deliberate.js`。 五个角色提示针对LLM生成裁决的散文解释 — 信用基本原理、风险官、公平贷款合规、客户倡导者、宏观对立派。 理由层是咨询性的。 它不能更改裁决；解析器已经运行。 有助于人类审查者构建不利行动通知叙述和内部审计工作文件。
**证明层** — `lib/attestation.js`。 Ed25519签署裁决、模型ID、输入承诺、输出承诺、previous_hash（链）和14个可选追加绑定（字典哈希、可复制性清单、采样种子承诺等）的规范序列化。 旧证明与新验证器代码一起验证，因为绑定是追加的，而不是插入的。
## 监管锚点
Shadow不声称是合规产品。 它生成的证据使受监管的贷款人可以向银行律师、内部审计工作文件审查员或州检察官提交证据。 2026年美国中级银行的主要钩子：
- **ECOA / Regulation B §1002.9不利行动通知的明确性。** 2026-07-21的Reg B最终规则在联邦层面缩小了差异影响的暴露。 §1002.9的具体主要原因义务未被修改，仍然具有约束力。 Shadow的签名原因代码字典（`lib/schemas/reason-code-dictionary.json`）是贷款人允许为给定裁决发出哪些代码的工件。
## API表面
信用决策垂直（v1.5.x → v2.0.0，已发货）：
- `POST /api/loan-council` — 仅限裁决引擎。 纯计算。 无LLM调用。 确定性。
- `POST /api/deliberate` — 裁决+理由。 调用LLM获取角色散文。 返回与 `/api/loan-council` 相同的裁决。
- `POST /api/verify-attestation` — 验证签名的决策。
- `POST /api/verify-chain` — 行走链并报告篡改检测。
- `GET /api/health` — 生存。
- `GET /api/attestation-info` — 公钥发现。
- `GET /api/mcp-manifest` — MCP工具表面的SBOM。
v3证据包（M2.3，2026-07-10发货）：
- `POST /api/evidence/events` — 证据包的通用HTTP摄取。 接受一个完整的会话（头+有序事件列表）在一个JSON正文中，返回一个签名的+链式验证的包，与 `spec/EVIDENCE_BUNDLE.md` 相匹配。 无状态； 服务器通过 `SHADOW_ATTESTATION_ED25519_PRIVATE_KEY` 持有Ed25519签名密钥。
## MCP集成
Shadow发货了一个9工具MCP服务器（`mcp/server.js`）可从Cursor、Claude Desktop、Zed或任何MCP客户端使用。 见 [`mcp/README.md`](./mcp/README.md).
## 威胁模型
记录在 [`docs/THREAT_MODEL.md`](./docs/THREAT_MODEL.md). 摘要：Shadow的Ed25519证明击败了**外部篡改** 和 **链重新排序/插入/截断**。 它 **不** 打败 **银行内部人员拥有私钥**。 如果您的威胁模型包括银行侧的历史重新签名，您需要在Shadow之上使用外部时间戳锚点（RFC 3161 TSA或公共透明度日志）。 Sigstore Rekor集成在v2.1路线图上。
## Shadow不是什么
- 不是认证的公平贷款验证器。 Shadow的理由层本身就是公平贷款验证的候选者。
- 不是银行决策引擎。 真实的银行贷款原始使用贷款原始系统+信用模型+人类贷款人。 Shadow证明。 它不做出决定。
- 不是SOC 2审计。 `docs/soc2-readiness.md`是一个自我评估就绪地图，而不是审计报告。
- 不旨在取代WORM日志记录+SIEM保留。 它们处理保管链。 Shadow添加了一个原因代码字典绑定，而WORM+SIEM无法生成。
## 旧内容
之前的README描述了实习导师、交易和数据科学角色包，这些都是实验性的，现在不再是发货产品。 存档在 [`docs/archive/README-v1-legacy.md`](./docs/archive/README-v1-legacy.md).
XR / spatial-council演示（`demo/xreal.html`）是2026年7月毕业设计和IEEE VR 2027摘要的研究制品，而不是银行产品。 将在毕业设计后移动到 `demos/xr/`，并在旧路径上有一个重定向存根。
## 许可证
MIT。 见 [`LICENSE`](./LICENSE).
## 贡献者
Alex Xiaoyu Ji（作者）。
Loredana C. Levitchi — 监管领域审查和BRD作者，风险/信贷政策/不利行动模块；源基础模式A BRD +增补A/B/C +风险食欲笔记，MIT许可合并，在2026-06-19的明确授予。
## 路线图
**v3证据层 — 状态 vs [`docs/roadmap/SHADOW_V3_BRIEF.md`](./docs/roadmap/SHADOW_V3_BRIEF.md)**（目标发货2026-08-02，EU AI Act第12条执行窗口）：
| 里程碑 | 状态 | 哪里 |
|---|---|---|
| M1.1 证据包规格 + JSON模式 | ✅ 已发货 | `spec/EVIDENCE_BUNDLE.md`，`spec/evidence-bundle.schema.json` |
| M1.2 流式API（`createSession` / `appendEvent` / `sealSession`） | ✅ 已发货 | `packages/attest-core/session.js` |
| M1.2 崩溃恢复 + FileStore | ✅ 已发货 | `packages/attest-core/store-file.js`，`recoverSession` + `sealPartialBundle` |
| M1.2 10k事件性能（< 5秒目标） | ✅ 69毫秒实际 | `test/session-perf-10k.test.js` |
| M2.1 Claude Code钩子适配器 | 🚧 下一个 | `packages/adapter-claude-code/`（计划中） |
| M2.2 OpenTelemetry GenAI适配器 | 🚧 计划中 | `packages/adapter-otel/`（计划中） |
| M2.3 通用HTTP摄取 | ✅ 已发货 | `api/evidence/events.js` |
| M3 外部锚点（RFC 3161 + Rekor） | 🚧 计划中 | — |
| M4 verify.html静态离线验证器 | ✅ 已发货 | [`verify.html`](./verify.html)， [`.github/actions/shadow-verify`](./.github/actions/shadow-verify) |
| M4 shadow-verify CLI + GitHub Actions | ✅ 已发货 | `bin/shadow-verify.mjs`，`.github/actions/shadow-verify/` |
| M5 法医重放（2D + XR） | 🚧 计划中 | — |
| M6 文档 + 启动叙述 | 🚧 计划中 | — |
**其他路线图文档：
- `docs/roadmap/SHADOW_XR_DEMO_BRIEF.md` — XREAL One Pro / WebXR演示轨道，用于毕业设计 + IEEE VR论文。
## 联系方式
Alex Xiaoyu Ji · xji1@mail.yu.edu
