> **从 pre-`mode` 版本升级？** 向后兼容性已保留：早于逐规则模式的政策（它设置了 `settings.block_categories`，但没有 `default_mode`，也没有规则级别的 `mode`）会保持其原有行为——当使用 `--mode enforce` 安装时，这些类别仍然会被阻止。一旦你的政策采用逐规则模型（任何 `mode`/`default_mode`），它就会完全按照上述描述成为政策权威。

---

## 架构<a name="how-it-works" />

每次工具调用都走同一条路径：它通过**集成表面**进入
（阶段 1），在**执行前被评估**（阶段 2），产生
允许/警告/阻止的裁决，并落入**防篡改证据**（阶段 3）。
阶段 4 是可选的——一个自托管控平面，其签名政策在设备注册后
成为阶段 2 的权威。```mermaid
flowchart TD

%% ── sources ────────────────────────────────────────────────
subgraph SRC["Agents Prismor protects"]
    direction LR
    AC["<b>Coding agents</b><br/>Claude Code · Codex · Cursor · Windsurf · Copilot<br/>OpenClaw · Hermes · Grok · Kiro · Crush<br/>OpenHands · Qwen · Continue · Goose"]
    AF["<b>Production frameworks</b><br/>OpenAI Agents · LangChain / LangGraph · CrewAI · browser-use<br/>Pydantic AI · AutoGen Core · Agno · Semantic Kernel · Google ADK<br/>BeeAI · Claude Agent SDK · Vercel AI SDK · Mastra"]
end

%% ── stage 1 ────────────────────────────────────────────────
subgraph ENTRY["Stage 1  ·  Integration surface"]
    direction LR
    H(["<b>Runtime hooks</b><br/>pre / post tool-call<br/>per-agent config"])
    G(["<b>MCP gateway</b><br/>fronts every MCP server<br/>injection-scans responses"])
    F(["<b>Framework adapters</b><br/>in-process + HTTP eval server<br/>per-user via use_subject"])
end

%% ── stage 2 ────────────────────────────────────────────────
subgraph EVAL["Stage 2  ·  Evaluated before the call executes"]
    direction TB
    D(["<b>Tool-call dispatcher</b>"])
    P["<b>Policy engine</b><br/>YAML rules · per-rule observe / enforce<br/>layered org → project → repo · non-overridable floor"]
    CHK["<b>Pre-execution checks</b><br/>Semantic guard · Egress control · MCP guardrails · Tool tags<br/>IAM and agent controls · Scoped session rules<br/>Script-content inspection · Docker sandbox"]
    SEC["<b>Secret and supply-chain protection</b><br/>Cloak placeholders + output scrub · Env guard · Sweep<br/>Canary tripwires · Skill scanner<br/>Supply-chain scoring → npm · pip · cargo · go"]
end

FEED[/"Signed advisory feed  ·  Prismor intel + NVD"/]
V{"<b>Allow  ·  Warn  ·  Block</b><br/>every block prints narrowest-first unblock steps"}

%% ── stage 3 ────────────────────────────────────────────────
subgraph EV["Stage 3  ·  Evidence and feedback"]
    direction LR
    ST[("<b>Session store</b><br/>SQLite + JSONL<br/>session forensics")]
    VIEW["<b>Views</b><br/>Web + terminal dashboard<br/>Status · Tokens · Audit · Doctor"]
    PROOF["<b>Tamper-evident</b><br/>Signed trail — hash chain + Ed25519<br/>Attestation bundle · Host discovery"]
    LEARN["<b>Learning</b><br/>propose rules · flag false<br/>positives · detect evasion"]
end

PAST[/"Transcript ingest  ·  replays pre-install history through the live policy"/]

%% ── stage 4 ────────────────────────────────────────────────
subgraph ORG["Stage 4  ·  Optional self-hosted control plane"]
    direction LR
    RP["<b>Signed remote policy</b><br/>layered rules · time-boxed<br/>exemptions · pause / resume"]
    TEL["<b>Live telemetry</b><br/>redacted events<br/>offline spool"]
    OD["<b>Org dashboard</b><br/>policy · devices<br/>sessions · approvals"]
end

%% ── flow ───────────────────────────────────────────────────
AC --> ENTRY
AF --> ENTRY
ENTRY --> D
D --> P
P --> CHK
P --> SEC
FEED -.-> SEC
CHK --> V
SEC --> V
V --> ST
PAST -.-> ST
ST --> VIEW
ST --> PROOF
ST --> LEARN
LEARN -.->|"proposed rules"| P
RP ==>|"authoritative once enrolled"| P
ST -->|"redacted"| TEL
TEL --> OD

会话、发现结果、威胁类别、代理细分以及实时事件流——全部来自本地工作区数据库，无需云端。

<h3>自托管仪表盘</h3>

<img width="1500" height="771" alt="image" src="https://assets.kitploit.com/production/public/readmes/13903/4803ea2755c08fa3f6d987eea1a23e0db9aa8d18d748f0160fee2e19cce765f2.png" />


### 供应链强制管控<a name="supply-chain-enforcement" />

`prismor` 封装了你的包管理器，并在每次安装运行前，依据实时威胁情报对其进行评分——涵盖年龄、维护者数量、安装脚本以及已知的入侵指标（IOC）。内置对 **mini-shai-hulud**（2026年5月）和 **AntV 维护者劫持** 攻击（2026年5月）的覆盖。```bash
prismor supplychain npm install express                    # passes, runs npm
prismor supplychain npm install @tanstack/react-router     # BLOCK: IOC match (score 100)
prismor supplychain pip install requests numpy
prismor supplychain pnpm add lodash

参见 [docs/supply-chain.md](https://github.com/prismorsec/prismor/blob/main/docs/supply-chain.md) 获取完整的评分表、生态系统支持以及 IOC 格式。

---

## 禁用 Prismor<a name="disabling-prismor" />

有三个相互独立的层级，每一层都可以限制代理会话。禁用其中一层并不会禁用其他层——请选择与你实际想要关闭的内容相匹配的层级。

### 1. 完全卸载钩子

从代理的钩子配置中移除 `hook-dispatch` 条目，这样 Prismor 将完全不再接收 `PreToolUse`/`PostToolUse`/`UserPromptSubmit` 事件。```bash
prismor uninstall-hooks --agent claude --scope project   # this workspace only
prismor uninstall-hooks --agent claude --scope user      # global (all workspaces)
prismor uninstall-hooks --agent all --scope project      # every supported agent, this workspace

`--mode observe` 会记录发现结果而不进行拦截。`PRISMOR_LOCAL_DRY_RUN=1` 还会额外抑制对任何发现的拦截，否则这些发现在以 observe 模式安装的钩子下会被拦截（`prismor/runtime/cli.py`，在 `args.mode == "observe"` 时检查）。如果你希望 Prismor 的遥测/日志功能继续工作，同时暂时停止强制执行，这就是正确的开关。

这**不会**影响 `.prismor/policy.yaml` 中设置为 `mode: enforce` 的策略规则——无论钩子是如何安装的，这些规则仍然以策略为权威（参见上文 [Observe / Enforce](#observe--enforce-per-rule-policy-authoritative)）。

### 3. 清除会话的作用域代理规则

[Scoped Agent](https://github.com/prismorsec/prismor/blob/main/docs/scoped-agent.md) 会在 `.prismor/scoped/{session_id}.json` 中合成每个会话的 `allowed_tools`/`deny_tools` 列表。**此检查独立于钩子的 `--mode`**——`deny_tools` 中的工具在 `prismor/runtime/scoped_agent.py` 中被硬编码为 `action: block` / `mode: enforce`，因此即使钩子以 `--mode observe` 安装，它也会进行拦截。卸载钩子或切换到 observe 模式不会解除作用域内的拒绝。```bash
prismor scope list                    # find the session ID
prismor scope show ID                 # inspect its allowed_tools / deny_tools (`latest` works too)
prismor scope clear ID                # remove the scoped rules for that session
prismor scope edit ID                 # or hand-edit deny_tools in $EDITOR