sieve CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

---

项目一句话

Sieve 是一个完全本地运行的 LLM 流量代理（Rust 单二进制），夹在 AI 编码 agent（Claude Code / OpenClaw / Hermes / Codex CLI）和上游模型 API（Anthropic / OpenAI / 中转站）之间，对 crypto 开发者做双向安全检测，在不可逆动作（签名 / 转账 / 部署）前强制插入认知摩擦。

项目状态

早期预览（0.1.0-alpha）。

能力面：双向检测（出站脱敏自动改写不弹窗 + 入站 fail-closed 拦截 Critical 工具调用）、四路由内容类型对等覆盖（Anthropic/OpenAI × SSE/JSON）、出站 exfil 链与 canary 诱饵检测、WIF/xprv 私钥格式检测、配置化路由表 [[upstream.routes]]、ProviderCodec 协议分层、四家 agent 接入。Cargo workspace 8 个 crate；sigstore + 可复现构建 CI 在跑。daemon ↔ client 走 IPC（JSON-RPC over Unix socket，协议版本白名单仅 v2，权威源 SPEC-005）。源码在 crates/ 下。

---

Source of Truth 层级

文档冲突时按以下优先级裁决（高 → 低）：

1. IPC 协议规格 — docs/specs/SPEC-005-ipc-protocol.md（IPC wire schema 唯一权威源）+ 其余 docs/specs/ 功能规格
2. 架构 / 数据模型 — docs/design/architecture.md + docs/design/data-model.md
3. API / 部署 / 开发指南 — docs/api/ + docs/guides/
4. README + .cursorrules — 项目入口与代码规范

约束：

• 改 IPC 字段先改 SPEC-005，再落代码
• 术语首次出现先去 docs/glossary.md 加条目，再在 SPEC 引用

---

不可放宽的硬约束（十六条 / .cursorrules §二）

任何 PR / 设计变更触碰以下任一条，默认拒绝，必须先和用户显式确认才能放宽：

1. Rust 栈非选项 —— Go regexp 慢 1000 倍；hot loop 不允许引入非 Rust 二进制依赖
2. 绝不联网做 verifier —— 任何外部 token / 签名 / 规则的远端校验都摧毁产品定位。唯一允许的出站：①上游 LLM API（用户主动调）②updates.sieveai.dev manifest（带 ?v=&os=&arch=&uid=&ch= 5 字段,可关）③cdn.sieveai.dev 规则正文（更新通道协议）
3. fail-closed High-Risk Tool Policy Gate —— 签名 / shell / 敏感路径的 Critical 工具调用强制人工确认，YOLO mode 不可关
4. BIP39 必须做 SHA-256 checksum 验证 —— 仅词表匹配不足以定级 Critical（Sieve 差异化点）
5. SSE 边界处理 fuzz test 全覆盖 —— 半行 chunk / 跨 chunk 分隔符 / C0 控制字符 / 多 event 粘包 / 提前断流，PR 不带 fuzz 不合并
6. 自身供应链 sigstore + reproducible build + pinned deps —— Tier 1（macOS / Linux）Week 1 起强制；Windows 为 Tier 2
7. Critical 拦截 FP < 0.5% —— 超过即用户禁用产品
8. Critical 在所有版本（含降级模式）不可关闭 —— 产品安全承诺，不是用户偏好
9. 适配四家 agent：Claude Code / OpenClaw / Hermes / Codex CLI —— UnifiedMessage 真实运行时支持 Anthropic Messages API + OpenAI Chat Completions 双协议；Codex CLI 走原生 PreToolUse hook（~/.codex/hooks.json）经 IPC judge_tool_call 取裁决，OpenClaw / Hermes 两家 hook 作 UX 层、安全不变量由网关 inbound_hold 兜底 fail-closed；其他协议（Gemini / Mistral 等）推 Phase 2
10. GA 一次性公开 repo + 代码 + 文档 —— sigstore CI pipeline 照常跑通
11. 不在 Anthropic API 协议层撒谎 —— 不伪造 tool_use / stop_reason / id / usage / type；拦截发生时允许截 SSE 流注入 sieve_blocked event（Sieve 自报事件，不是冒充模型）；keep-alive comment 行 : keep-alive\n\n 不属于伪造
12. 不装本地 CA 做 MITM —— Network Extension / 本地 CA 注入 / 系统 proxy 修改推 Phase 3 选购，Phase 1/2 不做
13. 出站脱敏不打断工作流 —— OUT-01~05/12 高频脱敏类必须自动脱敏 + 状态栏 5s 通知，不弹窗；每天弹几十次的产品没人用
14. 用户规则系统 fail-safe（v2.0）—— 用户规则文件加载失败 / pattern 编译失败 / 安全 lint 拒绝 → daemon 必须正常启动 + 系统规则全功能；用户规则不能 override 或 suppress 系统 Critical；用户规则只能 High Ask/Warn/Mark，不能 Block / HookTerminal。详见 LayeredEngine 合并顺序
15. 行为序列检测保守起步 + 默认关闭（v2.0）—— IN-SEQ-* 仅触发 StatusBar 通知，不引入新 Block 路径；默认关闭（feature flag sequence_detection = false），用户主动 opt-in。升级为 Block 类需充分样本积累 + FP < 0.5% + 新决策记录。
16. 所有入站能力必须经过 content-type 路由矩阵测试（v2.0）—— 任何新增入站功能必须有集成测试覆盖 4 类组合（Anthropic SSE / Anthropic JSON / OpenAI SSE / OpenAI stream=false JSON）；新功能只挂 SSE 不挂 JSON 视为 P0 漏洞。