内容
# CyClaw
> **离线优先，RAG 强制，安全的本地 AI "第二大脑"，带有 Dropbox 同步功能，用于数据/语料库/ + 安全，带外，默认禁用代理功能**
[](https://www.python.org/)
[](https://fastapi.tiangolo.com/)
[](https://github.com/langchain-ai/langgraph)
[](https://github.com/pgvector/pgvector/)
[](https://github.com/CGFixIT/CyClaw/actions/workflows/codeql.yml)
[](https://github.com/cgfixit/CyClaw/actions/workflows/ci.yml)
[](https://github.com/cgfixit/CyClaw/actions/workflows/devskim.yml)
[](https://github.com/cgfixit/CyClaw/actions/workflows/gitleaks.yml)
[](https://github.com/cgfixit/CyClaw/actions/workflows/osv-scanner.yml)
[](https://github.com/CGFixIT/CyClaw/tree/main/docs/screenshots)
[^CyClaw 网页应用本地 AI 聊天机器人截图^]
---
## 它能做什么
CyClaw 是一个个人 RAG（检索增强生成）后端：
1. **仅从本地 Markdown 语料库中回答问题** — 默认情况下不使用互联网
2. **通过 LangGraph 拓扑结构强制执行每种安全不变性** — 不是提示词，不是配置标志，不是纪律
3. **维护一个持久的灵魂/个性层** (`soul.md`)，具有 SHA-256 漂移检测，原子进化写入和用户门控修改
4. **在混合模式下，仅在用户明确确认的情况下回退到 Grok（xAI）** — 在配置、环境和每个查询级别上进行三重门控
5. **暴露 FastAPI HTTP 网关和 MCP 服务器**，用于 Claude Desktop / Copilot Studio 集成
6. **提供可选的带外操作层**，用于 Dropbox 语料库同步 (`sync/`) 和代理 GitHub 上下文/受控本地工作流 (`agentic/`，`.claude/`) — 永远不会导入请求路径，现在也可以通过受控的 **Sync** 和 **Agentic** 控制台从浏览器终端驱动
7. **将代理层扩展到本地数据**（v1.8），具有一个可选择的 **文件系统连接器** (`agentic/fsconnect/` — 有范围的读取 + 门控写入，TOCTOU 安全)和一个只读 **SQL 连接器** (`agentic/sqlconnect/` — 仅限 SELECT 的 Postgres/MSSQL 框架) — 两个功能默认禁用，带外
8. **添加一个可选的 NeMo Guardrails 内容安全层**（v1.8，`guardrails/`），它软导入 `nemoguardrails` 并降级为离线启发式轨道 — 深度防御，仅作为防御，而不是路由权限（图拓扑结构仍然是唯一的策略）
---
## 版本历史
| 版本 | 状态 | 主要更改 |
|---|---|---|
| v1.2.0 | 已被取代 | 8 个 OWASP 模式，90 天 TTL，消毒剂基线 |
| v1.3.0 | **Langgrinch 前** | 速率限制（60/分钟），13 个 OWASP 模式，灵魂 SHA-256 漂移检测，原子写入，TTL→365 天 |
| v1.4.0 | 已被取代 | Dropbox/云语料库同步（带外 rclone 包装器 + 完整审计集成）+ 要求.txt 固定为 Python 3.12 + 漏洞补丁 |
| v1.5.0 | 已被取代 | 带外代理层基础 + 内存编排节点 + Docker 加固 |
| v1.6.0 | 已被取代 | 代理版本：通过 `gh` 受控读取 GitHub 上下文，`受控本地技能注册表，`.claude/ 工作流/命令/模式/工具/实用提示，以及 README / 结构刷新 |
| v1.7.0 | 已被取代 | 浏览器 Sync + Agentic 操作控制台在终端 UI 中，通过循环访问仅限 `POST /ops/sync` + `POST /ops/agentic` 子进程隔离 |
| v1.8.0 | **生产（当前）** | 代理 **文件系统连接器** (`agentic/fsconnect/` — 有范围的读取，门控/原子写入，TOCTOU 安全 `pathsafe` 核心，可选 RAG 语料库索引）和只读 **SQL 连接器** (`agentic/sqlconnect/` — 仅限 SELECT 的 Postgres/MSSQL 框架）+ 可选 **NeMo Guardrails** 层 (`guardrails/` — 离线启发式轨道，优雅降级)。所有三个功能均为可选，默认禁用，带外（永远不会被 gate/graph/MCP 导入） |
---
## 架构
```
用户查询（HTTP POST /query 或 MCMC 工具调用）
│
▼
┌─────────────────────────────────────────────────────┐
│ gate.py （FastAPI，127.0.0.1:8787） │
│ • 速率限制（每 IP 60 请求/分钟 — 运行在第一个） │
│ • 注入过滤器（sanitizer.py，配置驱动） │
│ • 灵魂初始化（PersonalityManager 闭包） │
│ • 遥测杀死块（在任何 SDK 导入之前） │
└──────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ graph.py （LangGraph 7 节状态机） │
│ │
│ [入口] │
│ ↓ │
│ 1. 检索 （Chroma + BM25 + RRF 融合） │
│ ↓ │
│ 2. 路由评分 （top_score >= 0.028 RRF？） │
│ ├─ 是 ──→ 3. 本地_llm (LM Studio :1234) │
│ └─ 否 ──→ 4. 用户门控（needs_confirm=true） │
│ ├─ 确认 + 混合 ──→ │
│ │ 5. grok_fallback │
│ └─ 拒绝 / 离线 ──→ │
│ 6. 离线最佳努力 │
│ ↓ （所有路径汇聚） │
│ 7. 审计记录器（SHA-256 + PII 消除 → jsonl） │
│ ↓ │
│ [结束] │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ HybridRetriever （检索/hybrid_search.py） │
│ • ChromaDB （语义，全部 MiniLM-L6-v2，384d） │
│ • BM25Okapi （关键词，波特词干提取） │
│ • RRF 融合（k=60，等权重） │
│ • 每结果的元数据提供信息 │
└─────────────────────────────────────────────────────┘
```
### LangGraph 拓扑结构（渲染）
```mermaid
flowchart TD
A(["🌐 客户端\nHTTP POST /query\n或 MCP 工具调用"])
A --> B
subgraph GATEWAY ["gate.py — FastAPI 127.0.0.1:8787"]
B["TrustedHostMiddleware\n主机头允许列表"]
B --> C["速率限制器\n每 IP 60 请求/分钟"]
C --> D["提示注入过滤器\n33 个模式 · 配置驱动 · lru_cache"]
D --> E["构建 GraphState\n查询 + 用户确认在线"]
end
E --> F
subgraph GRAPH ["graph.py — LangGraph 7 节状态机"]
F(["① 检索\nChroma + BM25 + RRF"])
F --> G["② route_by_score\ntop_score ≥ 0.028？"]
G -->|"YES — 本地上下文"| H["③ local_llm\nLM Studio :1234\nQwen2.5-7b"]
G -->|"NO — 保险库丢失"| I["④ user_gate\nneeds_confirm = true"]
I -->|"confirmed=true\n+ 混合 + grok.enabled"| J["⑤ grok_fallback\nxAI grok-4.3\n三重门控"]
I -->|"confirmed=false\n或离线模式"| K["⑥ offline_best_effort\n本地 LLM · 无 RAG 门控"]
H --> L
J --> L
K --> L
L(["⑦ audit_logger\nSHA-256 哈希 · PII 消除\n→ logs/audit.jsonl"])
end
L --> M(["📤 查询响应\n答案 · 来源 · model_used\n检索模式 · needs_confirm"])
subgraph RETRIEVAL ["retrieval/hybrid_search.py"]
N["ChromaDB\n语义 · 384-dim 余弦"]
O["BM25Okapi\n关键词 · 波特词干提取"]
P["RRF 融合\nk=60 · 等权重"]
N --> P
O --> P
end
F <-->|"混合搜索"| P
subgraph SOUL ["utils/personality.py"]
Q["soul.md\nSHA-256 漂移检测"]
R["SQLite / Postgres\n版本历史 · TTL 剪枝"]
Q <--> R
end
H <-->|"灵魂前缀\n≤ 8000 字符"| Q
K <-->|"灵魂前缀"| Q
subgraph OOB ["带外 — 永远不会被 gate/graph/MCP 导入"]
S["agentic/cli.py\nGitHub 读取操作"]
T["agentic/fsconnect/\n本地文件系统连接器"]
U["sync/cli.py\nDropbox 语料库拉取"]
V["guardrails/\nNeMo 轨道骨架"]
end
style GATEWAY fill:#1a3a5c,color:#ffffff,stroke:#4a90d9
style GRAPH fill:#1a3a2a,color:#ffffff,stroke:#4a9d5a
style RETRIEVAL fill:#3a2a1a,color:#ffffff,stroke:#d9904a
style SOUL fill:#3a1a3a,color:#ffffff,stroke:#d94ad9
style OOB fill:#2a2a2a,color:#aaaaaa,stroke:#666666,stroke-dasharray:5 5
style J fill:#5c1a1a,color:#ffffff
style L fill:#1a1a3a,color:#ffffff]
```
---
## API 密钥设置（灵魂突变）
CyClaw 的灵魂突变端点（`/soul/propose`、`/soul/apply`、`/soul/reload`、`/soul/restore`）需要一个 **Bearer API 密钥**。没有它，它们会立即返回 `HTTP 401` — 故意关闭行为。
> **所有 `/soul/*` 端点 — 包括 `GET /soul` — 都需要有效的 `Authorization: Bearer <key>` 令牌。** 只有 `/health` 和 `/query` 是未经身份验证的。
### Windows — PowerShell
为当前会话设置（终端关闭时清除）：
```powershell
$env:CYCLAW_API_KEY = "您的强大本地密钥"
uvicorn gate:app --host 127.0.0.1 --port 8787```
跨会话持久（永久写入当前用户的环境）：
```powershell
[System.Environment]::SetEnvironmentVariable(
"CYCLAW_API_KEY",
"您的强大本地密钥",
[System.EnvironmentVariableTarget]::User
)
# 重新启动您的终端，然后正常启动：
uvicorn gate:app --host 127.0.0.1 --port 8787```
验证它是否已设置：
```powershell
echo $env:CYCLAW_API_KEY
```
### Windows — 命令提示符（cmd.exe）
```cmd
set CYCLAW_API_KEY=您的强大本地密钥
uvicorn gate:app --host 127.0.0.1 --port 8787```
永久持久（在新会话中生效）：
```cmd
setx CYCLAW_API_KEY "您的强大本地密钥"
```
### Windows Server 2022 — 系统范围（所有用户，需要管理员）
```powershell
[System.Environment]::SetEnvironmentVariable(
"CYCLAW_API_KEY",
"您的强大本地密钥",
[System.EnvironmentVariableTarget]::Machine
```
或通过 GUI：**系统属性 → 高级 → 环境变量 → 系统变量 → 新建### Linux / macOS — Bash / Zsh
为当前会话设置：
```bash
export CYCLAW_API_KEY="您的强大本地密钥"
uvicorn gate:app --host 127.0.0.1 --port 8787```
在您的 shell 配置文件（`~/.bashrc`、`~/.zshrc` 或 `~/.profile`）中持久：
```bash
echo 'export CYCLAW_API_KEY="您的强大本地密钥"' >> ~/.bashrc
source ~/.bashrc
uvicorn gate:app --host 127.0.0.1 --port 8787
```
为 **systemd 服务**（Linux 服务器）持久：
```ini
# /etc/systemd/system/cyclaw.service
[Unit]
Description=CyClaw RAG Gateway
After=network.target
[Service]
Type=simple
User=cyclaw
WorkingDirectory=/opt/CyClaw
Environment="CYCLAW_API_KEY=您的强大本地密钥"
Environment="GROK_API_KEY=offline-dummy-sk-123"
ExecStart=/opt/CyClaw/.venv/bin/uvicorn gate:app --host 127.0.0.1 --port 8787
Restart=on-failure
[Install]
WantedBy=multi-user.target
```
```bash
sudo systemctl daemon-reload
sudo systemctl enable --now cyclaw
```
### 所有平台 — `.env` 文件（已包含在 `.gitignore` 中）
在仓库根目录创建 `.env`:
```
CYCLAW_API_KEY=您的强大本地密钥
GROK_API_KEY=offline-dummy-sk-123
```
在启动前加载：
```bash
# Bash / Zsh
export $(grep -v '^#' .env | xargs)
uvicorn gate:app --host 127.0.0.1 --port 8787
```
```powershell
# PowerShell
Get-Content .env | ForEach-Object {
if ($_ -match '^([^#=][^=]*)=(.*)$') {
[System.Environment]::SetEnvironmentVariable($Matches[1].Trim(), $Matches[2].Trim())
}
}
uvicorn gate:app --host 127.0.0.1 --port 8787
```
### 选择密钥值
CyClaw 仅限于环回访问 (`127.0.0.1:8787`) — 密钥永远不会跨网络传输。尽管如此：
- 至少使用 **20 个随机字符**：`openssl rand -hex 20`（Linux/macOS）或 `[System.Web.Security.Membership]::GeneratePassword(24,4)`（PowerShell）
- 不要重用其他地方的密码
- 不要将密钥提交到 Git（`.env` 已包含在 `.gitignore` 中）
## 快速开始
### 先决条件
| 需求 | 版本 | 备注 |
|---|---|---|
| Python | 3.12 | 主要支持的运行时 |
| [LM Studio](https://lmstudio.ai/) | 任意 | 必须在 `localhost:1234` 上运行 |
| 加载到 LM Studio 中的 GGUF 模型 | — | `mistral-7b-instruct` 或 `qwen2.5-7b` 效果良好 |
### 安装
```bash
git clone https://github.com/CGFixIT/CyClaw
cd CyClaw
python3.12 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# 1) 首先安装仅限 CPU 的 torch（CVE-2025-32434 在 2.6.0 中修复，在 2.12.1 中修复范围内）
pip install torch==2.12.1+cpu --index-url https://download.pytorch.org/whl/cpu
# 2) 安装已固定到已验证的传输树中的其余部分。
pip install -r requirements.txt -c constraints.txt
```
### 所需的本地准备
```bash
mkdir -p data/personality index logs
printf '# Soul\n' > data/personality/soul.md
export GROK_API_KEY=dummy
```
### 运行
```bash
python -m retrieval.indexer
uvicorn gate:app --host 127.0.0.1 --port 8787
```
打开 `/` 以获取终端 UI，`/health` 以获取就绪状态。终端公开了三个操作员控制台 — **Soul**、**Sync** 和 **Agentic** — 后两个通过 `POST /ops/sync` 和 `POST /ops/agentic` 调用 `POST /ops/sync` 和 `POST /ops/agentic`（API 密钥门控，速率限制，审计）。
---
## 项目结构
```text
CyClaw/
├── gate.py
├── graph.py
├── config.yaml # 单一真实来源
├── README.md
├── Dropbox_Sync_Guide.md
├── mcp_hybrid_server.py # 仅限检索的 MCP 服务器
├── agentic/ # 带外 GitHub 上下文 + 受控注册表
│ ├── cli.py
│ ├── context.py
│ ├── gh_client.py
│ ├── registry.py
│ ├── writer.py # 写入脚手架，当前未执行
│ ├── fsconnect/ # (v1.8) 本地/ SMB 文件系统连接器
│ │ ├── cli.py
│ │ ├── client.py # 有范围的读取（fs_list/stat/read/grep）
│ │ ├── pathsafe.py # TOCTOU 安全核心，防止打开 O_NOFOLLOW
│ │ ├── writer.py # 门控，原子写入（默认禁用）
│ │ └── indexer.py # 可选的 RAG 语料库索引共享
│ └── sqlconnect/ # (v1.8) 只读 SQL 框架（Postgres/MSSQL）
│ ├── cli.py
│ └── client.py # 仅限 SELECT 查询保护，环境变量 DSN
├── guardrails/ # (v1.8) 可选 NeMo Guardrails 层（带外）
│ ├── cli.py
│ ├── config.py
│ ├── integration.py # 软导入 nemoguardrails；优雅降级
│ ├── rails.py # 离线启发式轨道（注入/灵魂/接地）
│ ├── metrics.py # 单独的 logs/guardrails.jsonl 流（仅哈希）
│ └── config/ # NeMo config.yml + rails.co（Colang 流）
├── .claude/ # 本地操作员工作流和提示
│ ├── commands/
│ ├── hooks/
│ ├── memory/
│ ├── patterns/
│ ├── rules/
│ ├── skills/
│ ├── tools/
│ └── utility-prompts/
├── retrieval/
│ ├── indexer.py
│ ├── hybrid_search.py
│ ├── embeddings.py
│ └── stemmer.py
├── llm/
│ └── client.py
├── sync/ # 可选 Dropbox 语料库同步
│ ├── cli.py
│ ├── runner.py
│ └── scheduler.py
├── utils/
│ ├── sanitizer.py
│ ├── logger.py
│ ├── personality.py
│ ├── health.py
│ └── ratelimit.py
├── tests/
├── docs/
├── static/
├── data/
│ ├── corpus/
│ └── personality/
└── .github/workflows/
```
---
## Dropbox 语料库同步
CyClaw 包括一个 **可选的** 带外 Dropbox 同步层，它将 Dropbox 语料库镜像到 `data/corpus/`，而不会触及 `gate.py`、`graph.py` 或 MCP 请求路径。
**主要功能**
- 使用安全熔断器（`max_delete`、`max_transfer`）的 `rclone` 备份拉取同步
- 更改的语料库文件的审计日志记录
- Linux 和 Windows 的可选调度器集成
- 语料库更改时的可选重新索引触发
**核心命令**
```bash
python -m sync.cli test
python -m sync.cli sync --dry-run
python -m sync.cli sync
python -m sync.cli status
python -m sync.cli schedule
python -m sync.cli unschedule
```
相同的操作也可以通过终端 UI 中的 **Sync 控制台**面板使用 `POST /ops/sync`（仅限环回，API 密钥门控，审计）。
参见 `Dropbox_Sync_Guide.md` 以获取完整的设置和调度详细信息。
---
## 代理层（v1.6.0）
CyClaw 现已包括一个 **简洁、受控的代理层**，用于本地操作员工作流。它是 **可选的、默认禁用的，并且完全带外**：它永远不会被 `gate.py`、`graph.py` 或 `mcp_hybrid_server.py` 导入。
### 它添加的内容
- **只读 GitHub 上下文**，通过 `gh` CLI
- **受控的本地技能注册表**，具有明确的人类门控
- **项目工作流和操作员帮助程序**，位于 `.claude/`
- **可重用的本地模式**，用于内存、命令、工具、钩子和实用提示
### 安全姿态
- 正常操作时仅读取
- 没有 GitHub 令牌被存储或转发到 CyClaw
- `gh` 作为 argv 列表调用，而不是通过 shell 执行
- 写行为仍然是脚手架的，并且在当前版本中不可执行
- 所有代理读取、拒绝和注册表更改都经过审计日志记录
###
```yaml
agentic:
enabled: true
repoCGFixIT/Caw"
mode: "read"
writes_enabled: false
gh_min_version: "2.40.0"
registry_path: "data/agentic/skills_registry.json"
```
### 主要的 agentic 命令
```bash
python -m agentic.cli status
python -m agentic.cli context --repo
python -m agentic.cli context --pr 123 -m agentic.cliissue 45
python -m agentic.cli test
python -m agentic.cli propose-skill --name deploy --desc "...body-file s.md --reason "draft"
python -m agentic-skill --name "..." --body-file s.md --reason "add deploy" --confirm
```
entic 控制台**面板通过 `POST /ops/agentic` 从终端 UI 驱动这些操作；技能应用在 4 个检查清单（`mode=write` + `writes_enabled` + `--confirm`）禁用 — 默认情况下仅限干预运行。
**agentic 文件夹中的关键区域**
- `skills/` — 可重复使用的项目技能/工作流
- `commands/` — 快捷命令入口点
- `patterns/` — 可重复的操作模式
- `tools/` — 工具包装器和帮助程序定义
- `utility-prompts/` — 可重复使用的操作员提示
- `memory/` — 面向内存的帮助程序/制品
- `hooks/` 和 `rules/` — 本地防护栏和自动化边界
**当前存储库的示例**
- 为 CyClaw 运行/测试工作流
- 架构、测试、日志记录和速度重构循环
- 会话结束工作流
- 内存编排支持模式
---
## 文件系统和 SQL 连接器（v1.8）
v1.8 将智能层 GitHub 以外的数据**，适用于受安全性要求高的使用场景，其中 AI 使用受到合规性两个连接器都是 **可选的，默认禁用，并且完全独立 永远不会被 `gate.py`、`graph.py` 或 `mcp_hybrid_server.py` 导入，因此五个安全变量通过构造保持不变。在禁用时，它们的 CLI 是纯粹的无操作（退出 0### `agentic/fsconnect/` — 本地/SMB 文件系统连接器
作用域 **读取** 和单独的门控** 到本地或 SMB 文件共享，共享一个 TOCTOU 安全核心。
- **`pathsafe.py` 安全核心** — POSIX `openat` / `O_NOFOLLOW` 从一个固定的根目录文件描述符（因此根目录不能在进程下被交换）。拒绝 UNC、NTFS 备用数据流 (`file::$DATA`)、`\\?\` / `\\.\` 设备路径、`..` 遍历和任何符号链接/重新解析点。分段感知包含关闭 **CVE-2025-53110** （兄弟前缀）和 `realpath` + `O_NOFOLLOW` 关闭 **CVE-2025-53109** （符号链接/连接逃逸）。
- **读取** (`fs_list` / `` / `fs_read` / `fs_grep`) 限定在 `allowed_roots` 内，审核，带有 5 MiB 读取上限和咨询 OWASP∪`banned_patterns扫描。
- **写入** (`fs_write` / `fs_append` / `fs_mkdir` / `fs_move`) — 完全构建但 **`writes_enabled: false` 默认**；单独的 `writable_roots` 列表中人为 `reason` + `--confirm` 门控（对于操作）；原子性（`tmp` + `os.replace`）；**内容无关** （从不调用 LLM — 操作员 LLM/QWEN 输出）。代码级 `FS_WRITE_HARD_DISABLE` 杀死开关强制干预，无论配置```bash
python -m agentic.cli status
python -m agentic.fsconnect.cli read <path> # 作用域读取
python -m agentic.fsconnect.cli grep <path> <pattern>
python -m agentic.fsconnect.cli write <path> --reason "..." # 除非启用写入预
python -entic.fsconnect.cli index --apply # 阶段共享 → 语料python -m agentic.fsconnect.cli test # 预检
```
在 `config.yaml` 中启用：
```yaml
fsconnect:
enabled: true
allowed: ["/srv/share"] # 启用时必需目录
max_file_bytes: 5242880 5 MiB 读取上限
writes_enabled: false # 主写入开关（在 false 时计划干预）
writable_roots: [null] # null => 操作系统默认值（/var/lib/cyclaw C:\CyClaw-FS）
max_write_bytes: 10485760 # 10 MiB 写入上限
index_enabled:切换共享的 语料库索引### `agentic/` — 只读 SQL（v0.1 框架）
一个默认禁，用于只读本地 SQL（Postgres / MSSQL）。只读通过三种方式强制执行SELECT/WITH-only 查询（通过扫描引用剥离副本拒绝 DDL/DML、堆叠语句和隐藏关键字）、**会话级只读** 事务和硬 `allow_write: false`。DSN 仅从 **环境变量** 读取（`CYCLAW_SQL_DSN`），从不硬编码；驱动程序（`psycopg` / `pyodbc`）延迟导入。
```bash
python -m agentic.sqlconnect.cli status
python -m agentic.sqlconnect.cli schema # 列出表架构（只读）
m agentic.sqlconnect.cli query --table public.users 界预览
python -m agentic.sqlconnect.cli```
```yaml
sqlconnect:
enabled: false
: "postgres" postgres" | ""
dsn_env: "CYCLAW_SQL_DSN" # 仅来自此环境变量的 DSN
statement_timeout_ms: 5000
max_rows: 1000
allow_write: false # 保留0.1 无论无法写入
```
NeMo 防护栏1.8）
`guardrails/` 中的 **可选、独立** 内容安全层。它是 **防御深度**，而非路由权限：LangGraph 拓扑结构仍然是策略的唯一来源。`guardrails:` 块的缺失或 `enabled: false` 是纯粹的无操作。 它从不被 `gate.py`、`graph.py` 或 `mcp_hybrid_server.py` 导入。
- **`nemoguardrails` 是可选依赖项。** 该层 **软导入** 它，当它不存在时，降级为 **离线启发式防护栏**，不需要第二个 LLM 调用：
**输入** — 轻提示注入标记扫描 + 灵魂/身份变异意图检测（灵魂治理不变层臂）；
输出** — 非基于事实（幻觉的 **接地** 检查，针对检索的上下文 重叠，低于 `hallucination_threshold`。
-oguardrails` **存在** 时，相同的 Python 检查会检查实时 NeMo 操作（通过 `guardrails/config/rails.co` 中的 Colang 流），因此离线式和实时防护栏漂移。
- 决策被记录到一个 ** 的指标流（/guardrails.jsonl该流 **仅存储 SHA-256 哈希值** — 永远不会存储原始 镜像审计日志的隐私立场。
```bash
python -m guardrails.cli status # 配置 + nemoguardrails 可用性
python -m guardrails.cli check "your query here" # 运行离线防护栏（无需 LLM/NeMo）
python -m guardrails.cli metrics # 总结防护栏流
python -m guardrails # 预飞行自检
```
```yaml
:
enabled: # 可选；当为 false 时，什么也不运行
engine: "openai" # LM Studio / Ollama OpenAI 兼容
model: "qwen2.5--instruct" models.local_llm.model 保持同步
hallucination_threshold: 0.18 # 接地轨道的 token 重叠下限
metrics_path: "logs/guardrails.jsonl" # 与 logs/audit.jsonl 分开（仅哈希值）
```
> 完整设计/线路计划：`docs/NeMo/later_development_guideline.md`。
---
## MCP 服务器
适用于 Claude Desktop 或其他 MCP 兼容客户端：
```json
{
"mcpServers": {
"cyclaw": {
"command": "python",
"args": ["/path/to/CyClaw/mcp_hybrid_server.py"]
}
}
}
```
MCP 服务器公开了一个仅限检索的 `hybrid_search` 工具。它 **没有采样能力** ，并且故意与智能、文件系统/SQL 连接器、NeMo 防护栏和 Dropbox 语料库同步层隔离。
---
## 安全模型
| 层 | 机制 |
|---|---|
| 网络 | 绑定 `127.0.0.1:8787` — 默认情况下无外部暴露 |
| 输入 | 配置驱动的注入过滤器 (`policy.prompt_filter`) |
| 速率限制 | 每 IP 60 req/min |
| 遥测 | 在 `gate.py` 中任何 SDK 导入之前杀死块运行 |
| 审计 | 所有路径记录 SHA-256 查询哈希 + PII 屏蔽元数据 |
| Grok 门控 | 三重门控：`mode=hybrid` AND `grok.enabled=true` AND `user_confirmed_online=true` |
| 灵魂写入 | 显式人为原因字符串 + 强制写入边界扫描 + 原子写入 |
| 智能写入 | 当前版本中已存根/非执行 |
| 文件系统连接器 | 读取范围限定为 `allowed_roots` （5 MiB 上限）；写入默认为 OFF，限定在单独的 `writable_roots` 中，由人为 `reason` + `--confirm`，原子性；TOCTOU 安全 `pathsafe`拒绝 UNC/ADS/设备路径/`..`/逃逸 |
|器 | 只读：SELECT/WITH-only 查询保护话只读 +_write: false`；DSN 仅来自环境变量；默认情况下禁用| 防护栏立、可选的深度防御；如果没有 `nemrails` ，则降离线启发栏；从不权限；单独的仅哈希指标流 |
| `/ops/*` 路由 | 仅限回环，`require_api_key` 门控，速率限制（60/min），每次调用都会审计（_sync_executed`ops_agentic_executed通过 `subprocess.run([...])` 调用 —导入 `sync/` 或 `agentic/` |
| 容器 | 非 root，-new-privileges` ，`cap_drop: ALL` ，只读 rootfs，，资源限制；可选 eBPF/Falco 检测（`deployco/`，默认关闭） |
> **范围：** CyClaw 是一个单一操作员、绑定回环的本地服务器。完整的威胁模型 — 沙盒的作用和 **
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器