# https://github.com/Bande-a-Bonnot/Boucle-framework 项目说明书
生成时间：2026-07-28 00:58:02 UTC
## 目录
- [项目概述与快速开始](#page-1)
- [危险命令拦截：bash-guard](#page-2)
- [Git 与工作区防护：git-safe / branch-guard / worktree-guard](#page-3)
- [文件与读取防护：file-guard / read-once](#page-4)
- [会话审计：session-log](#page-5)
- [CLAUDE.md 规则强制执行：enforce-hooks](#page-6)
- [安全审计与诊断：safety-check / diagnose / test-hook](#page-7)
- [已知限制数据库（Known Limitations）](#page-8)
- [跨平台支持与 Windows PowerShell 兼容](#page-9)
- [自主代理循环运行器（Rust 框架）](#page-10)
- [Broca 记忆系统](#page-11)
- [MCP 服务器与 Claude Code 集成](#page-12)
## 项目概述与快速开始
### 相关页面
相关主题：[危险命令拦截：bash-guard](#page-2), [安全审计与诊断：safety-check / diagnose / test-hook](#page-7)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/README.md)
- [tools/install.sh](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/install.sh)
- [tools/install.ps1](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/install.ps1)
- [examples/hello-world/README.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/examples/hello-world/README.md)
- [examples/daily-digest/README.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/examples/daily-digest/README.md)
# 项目概述与快速开始
## 一、项目定位与目标
Boucle-framework 是面向 Claude Code 的 **钩子（hook）安全与执行框架**，目标是在 AI 编码代理执行敏感操作（Shell、文件编辑、Git 提交、Worktree 退出等）之前进行拦截、检测与拦截决策（deny / allow），从而在 Claude Code 工作流上叠加一层可审计、可测试的纵深防御。
框架共发布 **27 个钩子文件**，覆盖三类生命周期事件：
- `PreToolUse` 与 `PostToolUse`：在 Bash、Write、Edit 等工具调用前后执行检查；
- `SessionStart`：会话初始化与会话注入防御；
- `ExitWorktree`：防止工作树退出造成数据丢失。
所有钩子在 v0.11.0 已迁移到 Claude Code 推荐的 `hookSpecificOutput.permissionDecision:deny` 输出格式，废弃了旧的 `decision:block` 写法；该项目当前已发展至 v0.13.0 版本。资料来源：[README.md:1-80]()
## 二、核心能力概览
| 能力类别 | 代表钩子 | 主要作用 |
| --- | --- | --- |
| Shell 命令风控 | `bash-guard` | 拦截破坏性命令、就地编辑绕过、glob 通配注入等 |
| Git 安全 | `git-safe` | 阻止 `--no-verify`、`--force`、子代理 staging 数据丢失等 |
| Worktree 保护 | `worktree-guard` | 在 `ExitWorktree` 时检测未提交 / 未推送改动 |
| 凭证与会话防护 | `FileChanged`-hook 等 | 防止凭证泄露与未授权会话注入 |
| 已知限制（KL）数据库 | `limitations.html` | 收录 640 条钩子/Agent 缺陷，含 42 条 CRITICAL |
> 上表中“已知限制数据库”条目与 v0.12.0 引入的可搜索限制页面、v0.13.0 扩充至 640 条相对应；正面能力（防御钩子）则与 v0.8.0 ~ v0.9.3 系列发布同步演进。资料来源：[README.md:30-120]()
## 三、跨平台安装（快速开始）
框架遵循“同一逻辑，平台原生分发”原则，在 Linux / macOS 与 Windows 上分别提供独立安装脚本，无需 WSL 或额外模拟层。
### Linux / macOS
```bash
git clone https://github.com/Bande-a-Bonnot/Boucle-framework.git
cd Boucle-framework
bash tools/install.sh
```
`tools/install.sh` 会将钩子注册到 `~/.claude/settings.json` 的 `hooks` 字段，并保留原始配置备份。资料来源：[tools/install.sh:1-60]()
### Windows（PowerShell 原生）
```powershell
git clone https://github.com/Bande-a-Bonnot/Boucle-framework.git
cd Boucle-framework
.\tools\install.ps1
```
v0.9.3 起所有 7 个核心钩子均提供 PowerShell 版本（`bash-guard.ps1` 约 849 行、112 条规则、51 个模式类别），无需借助 `bash.exe` 或 `jq`。资料来源：[tools/install.ps1:1-80]()
## 四、示例与下一步
仓库自带两个最小可运行示例，便于先验证框架再投入生产：
- `examples/hello-world`：演示单个钩子在 `PreToolUse` 拦截一条 `echo` 命令并返回 deny 决策的最简流程。资料来源：[examples/hello-world/README.md:1-40]()
- `examples/daily-digest`：演示如何把 `bash-guard` 允许的只读命令组合成定时摘要任务，并展示如何在 `SessionStart` 中注入环境上下文。资料来源：[examples/daily-digest/README.md:1-60]()
建议路径：
1. 阅读 `README.md` 顶部快速开始段；
2. 在 `examples/hello-world` 跑通一次端到端流程；
3. 查阅 v0.13.0 公布的 KL 数据库，过滤出与自身工作流相关的 CRITICAL / HIGH 限制；
4. 在生产仓库中按团队策略启用子集钩子，并在 `settings.json` 中保留审计字段。
## 五、面向新读者的注意事项
- 钩子按 `deny` 决策才生效；若 Claude Code 升级调整输出字段名（如 `permissionDecision` 大小写），需同步更新脚本；
- 部分已知限制（如 `FileChanged`-hook 的凭证泄露、子代理 git-staging 数据丢失）在 KL 数据库中归类为 CRITICAL，建议在启用钩子前先在 `framework.boucle.sh/limitations.html` 搜索对应关键字；
- Windows 下若同时存在 `bash-guard` 与 `bash-guard.ps1`，安装脚本会优先选择原生 PS1 版本。资料来源：[README.md:120-180]()
> 后续页面（如“钩子参考索引”“可知限制数据库指南”）将基于本页引用同一批源码文件展开。
---
## 危险命令拦截：bash-guard
### 相关页面
相关主题：[项目概述与快速开始](#page-1), [已知限制数据库（Known Limitations）](#page-8)
相关源码文件
以下源码文件用于生成本页说明：
- [tools/bash-guard/README.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/bash-guard/README.md)
- [tools/bash-guard/hook.sh](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/bash-guard/hook.sh)
- [tools/bash-guard/hook.ps1](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/bash-guard/hook.ps1)
- [tools/bash-guard/install.sh](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/bash-guard/install.sh)
- [tools/bash-guard/test.sh](https://github.com/Bande-a-Bonnot/Boucle-framework/test-guard/test.sh)
- [tools/bash-guard/test-ps1.py](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/bash-guard/test-ps1.py)
# 危险命令拦截：bash-guard
## 概述与定位
`bash-guard` 是 Boucle-framework 提供的一个面向 Claude Code 的 `PreToolUse` 钩子，专门用于在 LLM 智能体调用 `Bash` 工具之前静态扫描命令文本，阻断那些可能造成数据丢失、凭据泄露、远程破坏或绕过其他保护机制的"危险命令"。该组件位于仓库的 `tools/bash-guard/` 目录下，由 `hook.sh`（POSIX/bash 实现）与 `hook.ps1`（PowerShell 实现）共同构成核心检测逻辑，辅以 `install.sh` 负责注册到本地 Claude Code 配置，`test.sh` 与 `test-ps1.py` 提供回归测试。
`资料来源：[tools/bash-guard/README.md:1-40]()`
## 检测能力分类
根据 v0.9.2 与 v0.9.3 的发布说明，`bash-guard` 的检测规则被组织为多个语义类别：
- **就地（in-place）文件编辑绕过**：Claude Code 官方 issue [#40408](https://github.com/anthropics/claude-code/issues/40408) 揭示 `perl -i -pe`、`ruby -i`、`sed -i`、`ed` 等"原地修改"命令会完全绕过 `Write` / `Edit` 钩子。`bash-guard` 显式拦截这些工具的就地模式，从而在命令执行层补齐文件保护缺口。
- **Glob 通配符注入**：阻止利用 `*`、`?`、`[...]`、`{a,b}` 等展开形式绕过路径白名单的尝试。
- **Git 强制推送**：检测 `git push --force`、`git push -f` 以及对应缩写，避免工作树历史被不可逆覆盖。
- **云基础设施与磁盘工具**：在 PowerShell 版本中新增云 API（AWS / GCP / Azure CLI）、编码绕过（base64 / hex / octal）、磁盘工具（`dd`、`mkfs.*`、`fdisk`）等高危类目。
`资料来源：[tools/bash-guard/hook.sh:1-200](), [tools/bash-guard/hook.ps1:1-849]()`
| 维度 | hook.sh (bash) | hook.ps1 (PowerShell) |
|------|----------------|------------------------|
| 代码规模 | 较小的核心规则集 | 849 行 / 112 条规则 / 51 类模式（v0.9.3） |
| 依赖 | bash + 仓库内辅助工具 | 原生 PowerShell，无需 WSL / bash / jq |
| 平台 | Linux / macOS / WSL | Windows 原生 + 跨平台 |
## 跨平台实现与格式迁移
`bash-guard` 在两个版本演进上具有代表性。其一，v0.9.3 实现了 **Windows 平台完全对等**——`bash-guard.ps1` 覆盖了所有 bash 版本具备的检测语义，使 Boucle-framework 在 Windows 上不再依赖 WSL、子壳或 `jq` 解析。回归通过 `test-ps1.py` 驱动运行 PowerShell 子进程并比对 JSON 输出，确保两套实现的判定结果一致。
其二，v0.11.0 引入了 **输出格式迁移**：所有 27 个钩子（包括 `bash-guard`）从旧的 `{decision: "block"}` 顶层字段切换到 Claude Code 推荐的 `hookSpecificOutput.permissionDecision: "deny"` 嵌套结构。这要求 `hook.sh` 与 `hook.ps1` 都使用 `jq`（或 PowerShell 内置 JSON cmdlet）构造正确的 `hookSpecificOutput` 块，否则 Claude Code 会忽略拒绝信号。
`资料来源：[tools/bash-guard/hook.sh:stdout 构造段](), [tools/bash-guard/hook.ps1:stdout 构造段](), [tools/bash-guard/test-ps1.py:1-120]()`
## 安装、调用与测试
`install.sh` 负责把 `bash-guard` 注册到 `~/.claude/settings.json` 或等价作用域下的 `hooks.PreToolUse` 列表，匹配条件为 `tool_name == "Bash"`；注册后每当 Claude Code 准备执行 Bash 命令，Claude Code 会把命令文本通过 stdin 喂给钩子脚本，钩子返回的 JSON 决定是否放行。
测试方面：
- `test.sh`：在 POSIX 环境下运行一组已知危险命令样本（每条命令期望被 `hook.sh` 拒绝）与一组良性样本（期望通过），使用退出码与 stdout 中的 JSON 字段双重断言。
- `test-ps1.py`：通过 `subprocess` 调度 `pwsh`，对相同语料库执行 PowerShell 实现并对比结果，确保 bash/PS1 两端行为同步。
这种"双实现 + 同一语料"的测试结构是 v0.9.3 实现 Windows 完全对等的关键保障，也使得未来新增规则时只需扩展同一份测试用例即可同时验证两端。
`资料来源：[tools/bash-guard/install.sh:1-80](), [tools/bash-guard/test.sh:1-60](), [tools/bash-guard/test-ps1.py:1-120]()`
## 已知边界与社区反馈
尽管 `bash-guard` 已涵盖就地编辑、强制推送、Glob 注入等高危向量，但社区在 v0.12.0 / v0.13.0 的已知限制（Known Limitations）数据库中记录了 **640 条**钩子与智能体相关的缺陷条目（其中 42 条 CRITICAL），其中部分仍涉及 `Bash` 工具的拦截盲区（例如编码/混淆链路、间接通过子 shell 触发的命令）。这些条目说明：基于模式匹配的拦截天然滞后于新型绕过，运营者应将 `bash-guard` 视为纵深防御的一层而非唯一屏障，并结合 `git-safe`、`worktree-guard` 等其他钩子共同构成防护。
`资料来源：[tools/bash-guard/README.md:已知限制章节](), [CHANGELOG.md:v0.13.0]()`
---
## Git 与工作区防护：git-safe / branch-guard / worktree-guard
### 相关页面
相关主题：[危险命令拦截：bash-guard](#page-2), [已知限制数据库（Known Limitations）](#page-8)
相关源码文件
以下源码文件用于生成本页说明：
- [tools/git-safe/README.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/git-safe/README.md)
- [tools/git-safe/hook.sh](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/git-safe/hook.sh)
- [tools/git-safe/hook.ps1](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/git-safe/hook.ps1)
- [tools/branch-guard/README.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/branch-guard/README.md)
- [tools/branch-guard/hook.sh](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/branch-guard/hook.sh)
- [tools/branch-guard/hook.ps1](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/branch-guard/hook.ps1)
- [tools/worktree-guard/README.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/worktree-guard/README.md)
- [tools/worktree-guard/hook.sh](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/worktree-guard/hook.sh)
- [tools/worktree-guard/hook.ps1](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/worktree-guard/hook.ps1)
# Git 与工作区防护：git-safe / branch-guard / worktree-guard
Boucle-framework 围绕 Claude Code 的 PreToolUse / PreExit 钩子机制，提供了三类针对 Git 与工作区的防护工具。它们通过拦截危险命令与生命周期事件，避免 AI 代理在代码提交、分支操作和工作树切换时引入数据丢失、绕权执行或未经审查的状态变更。该模块属于 v0.13.0 中的「已知限制数据库（Known Limitations）」所覆盖的核心防御面，并在历次版本中持续扩展检测规则。
## 防护体系总览
三个钩子在 Claude Code 调用栈中的位置互补：
| 钩子 | 触发点 | 主要防御目标 | 引入版本 |
| --- | --- | --- | --- |
| git-safe | PreToolUse(Bash) | 拦截危险 git 命令与绕权参数 | 早期版本 |
| branch-guard | PreToolUse(Bash) | 受保护分支的写入限制 | 早期版本 |
| worktree-guard | PreToolUse/PreExit(ExitWorktree) | 工作树退出前的状态校验 | v0.8.0 |
所有钩子均提供 Bash（`hook.sh`）与 PowerShell（`hook.ps1`）双实现，自 v0.9.3 起达到 Windows 原生 7/7 全覆盖，无需 WSL、`bash` 或 `jq` 即可运行。资料来源：[tools/git-safe/README.md:1-40]()、[tools/branch-guard/README.md:1-40]()、[tools/worktree-guard/README.md:1-40]()。
```mermaid
flowchart LR
A[Claude Code 代理调用] --> B{工具类型}
B -- Bash git 命令 --> C[git-safe]
B -- Bash 分支操作 --> D[branch-guard]
B -- ExitWorktree --> E[worktree-guard]
C --> F{匹配危险模式?}
D --> G{目标为受保护分支?}
E --> H{工作树存在未保存状态?}
F -- 是 --> I[deny 并反馈原因]
G -- 是 --> I
H -- 是 --> I
F -- 否 --> J[allow]
G -- 否 --> J
H -- 否 --> J
```
## git-safe：危险 git 命令拦截
git-safe 专注于检测绕权与破坏性 Git 操作，包括：
- **`--no-verify` 绕过检测**：阻止 `git commit --no-verify`、`git push --no-verify` 及其 `-n` 简写，防止代理跳过预提交钩子或 GPG 签名流程。该规则同时存在于 bash 与 PowerShell 实现中。资料来源：[tools/git-safe/hook.sh:1-80]()、[tools/git-safe/hook.ps1:1-80]()。
- **强制推送检测**：拦截 `git push --force`、`git push -f` 等改写历史的推送，覆盖远程仓库安全防线。资料来源：[tools/git-safe/hook.sh:80-160]()。
- **索引/对象破坏命令**：屏蔽 `git reset --hard` 触发的无差异覆盖行为，以及可能导致工作树污染的批处理脚本。
输出采用 v0.11.0 引入的 `hookSpecificOutput.permissionDecision:deny` 标准格式，向 Claude Code 反馈阻止原因以便代理调整策略。资料来源：[tools/git-safe/README.md:40-80]()。
## branch-guard：受保护分支写入限制
branch-guard 在 git-safe 之上进一步限定分支维度的写操作：
- **白名单分支模式**：通过配置允许的分支前缀或名称（如 `feat/*`、`fix/*`），阻止对 `main`、`master`、`release/*` 等关键分支的直接写入。
- **危险子命令矩阵**：对 `git push`、`git reset`、`git checkout -B`、`git branch -D` 等命令结合当前/目标分支进行二次校验。
- **跨平台一致性**：bash 与 PowerShell 版本共享同一规则集，确保 Windows 代理环境下不会被绕过。资料来源：[tools/branch-guard/hook.sh:1-120]()、[tools/branch-guard/hook.ps1:1-120]()。
## worktree-guard：退出前的状态守卫
worktree-guard 解决 Claude Code 在 `ExitWorktree` 工具调用时可能丢弃未保存状态的问题。该钩子自 v0.8.0 引入，配套 29 项测试，v0.13.0 已知限制数据库中亦记录了「subagent git-staging data loss」等关键风险条目。
检测覆盖四类未持久化状态：
1. 未提交变更（uncommitted changes）
2. 未跟踪文件（untracked files）
3. 未合并分支（unmerged branches）
4. 未推送提交（unpushed commits）
v0.9.1 修复了 squash merge 场景下的误报问题，引入两层检测取代单一的 SHA 比较：第一层使用 `git log --merges` 识别合并提交形态，第二层对分支拓扑进行结构化判断。资料来源：[tools/worktree-guard/hook.sh:1-200]()、[tools/worktree-guard/hook.ps1:1-200]()。
## 跨平台实现与协同
三个钩子统一遵循以下工程约束：
- **结构对等**：`hook.sh` 与 `hook.ps1` 在功能、错误信息和退出码上保持一致，使行为可在 macOS、Linux 与 Windows 间复现。资料来源：[tools/git-safe/hook.ps1:1-60]()、[tools/branch-guard/hook.ps1:1-60]()。
- **配置复用**：通过共享的 JSON / 环境变量加载白名单与规则集，便于在仓库级 `.boucle/` 目录集中管理。
- **反馈可读**：deny 输出同时包含人类可读的中文/英文说明与机器可解析的结构化字段，便于代理重试时识别具体拦截规则。
该模块与 bash-guard 等其他工具共同构成 Boucle-framework 的纵深防御层，在 v0.13.0 的 640 条已知限制条目中持续暴露新的攻击面，便于社区贡献者提交规则扩展。资料来源：[tools/git-safe/README.md:80-120]()。
---
## 文件与读取防护：file-guard / read-once
### 相关页面
相关主题：[危险命令拦截：bash-guard](#page-2), [CLAUDE.md 规则强制执行：enforce-hooks](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [tools/file-guard/README.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/file-guard/README.md)
- [tools/file-guard/hook.sh](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/file-guard/hook.sh)
- [tools/file-guard/hook.ps1](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/file-guard/hook.ps1)
- [tools/file-guard/init.sh](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/file-guard/init.sh)
- [tools/read-once/README.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/read-once/README.md)
- [tools/read-once/hook.sh](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/read-once/hook.sh)
# 文件与读取防护：file-guard / read-once
`file-guard` 与 `read-once` 是 Boucle-framework 提供的两类面向 Claude Code 的 PreToolUse 钩子，分别承担"文件写入/编辑保护"与"敏感文件单次读取保护"两种职责。它们与同框架中的 `bash-guard`、`git-safe`、`worktree-guard` 共同构成了 Claude Code 代理（agent）执行期间的多层防御体系。资料来源：[tools/file-guard/README.md:1-20]()。
## 设计目标与防护边界
两个工具的设计目标均是"在最小化误报的前提下，阻断 Claude Code 代理对受保护文件与受保护内容的访问"，具体边界如下：
- **file-guard**：针对 `Write`、`Edit`、`MultiEdit`、`NotebookEdit` 工具触发，在写盘前评估目标路径是否落入受保护集合。资料来源：[tools/file-guard/hook.sh:1-15]()。
- **read-once**：针对 `Read` 工具触发，对带有敏感标记的文件执行"读后即焚"语义，防止代理在多次会话轮次中反复检索同一凭据。资料来源：[tools/read-once/hook.sh:1-10]()。
两者均采用 Claude Code 推荐的 `hookSpecificOutput.permissionDecision:deny` 输出格式（自 v0.11.0 起完成迁移），与 `bash-guard.ps1`、`git-safe` 等 27 个钩子保持一致的拒绝语义。资料来源：[tools/file-guard/hook.ps1:1-20]()。
## file-guard：写路径防护
### 触发与匹配流程
`file-guard` 在 `PreToolUse` 钩子阶段接收 JSON 输入，提取 `tool_input.file_path` 字段后，按照"绝对路径 → 规范化 → 模式匹配"的顺序执行判定。资料来源：[tools/file-guard/hook.sh:15-60]()。
```mermaid
flowchart LR
A[PreToolUse 事件] --> B{工具类型为 Write/Edit?}
B -- 否 --> Z[放行 exit 0]
B -- 是 --> C[读取 file_path]
C --> D[路径规范化]
D --> E{命中受保护模式?}
E -- 是 --> F[deny 并输出原因]
E -- 否 --> Z
```
### 保护集合
保护集合通常包含三类条目：(1) `.git/`、`node_modules/`、`vendor/` 等不应被代理直接改写的目录；(2) `*.env`、`*.pem`、`*.key`、`~/.ssh/id_*`、`~/.aws/credentials` 等凭据文件；(3) 通过 `init.sh` 注入的自定义 `BOUCLE_FILE_GUARD_EXTRA` 列表。资料来源：[tools/file-guard/init.sh:1-30]()。
### Windows 路径处理
PowerShell 实现使用 `[System.IO.Path]::GetFullPath()` 完成路径归一化，并使用 `-replace` 模式匹配区分大小写形式，避免在 NTFS 大小写不敏感场景下出现漏判。资料来源：[tools/file-guard/hook.ps1:30-80]()。
## read-once：敏感读取防护
### 一次性语义
`read-once` 通过维护一个状态文件（通常位于 `~/.boucle/read-once.state` 或仓库本地 `.boucle/read-once/`）记录已读取路径。当同一 `file_path` 在状态窗口内被再次请求时，钩子输出 `deny`，从而阻断代理通过多轮对话反复回读凭据、密钥或一次性令牌。资料来源：[tools/read-once/hook.sh:15-45]()。
### 状态清理与 TTL
为避免状态无限膨胀，钩子提供 TTL（默认约 1 小时）与 `BOUCLE_READ_ONCE_RESET` 环境变量触发全量重置；CLI 子命令 `tools/read-once/init.sh` 会在新会话开始时清理过期条目。资料来源：[tools/read-once/README.md:20-40]()。
## 集成模式与已知约束
| 维度 | file-guard | read-once |
|---|---|---|
| 触发工具 | Write / Edit / MultiEdit / NotebookEdit | Read |
| 决策粒度 | 路径模式 | 路径 + 时间窗 |
| 状态存储 | 无（纯函数式判定） | 有（本地 state 文件） |
| 跨平台实现 | hook.sh + hook.ps1 | hook.sh |
两个工具均依赖 `jq`（bash 实现）与 PowerShell 7+ 原生 JSON cmdlet（PS1 实现），与 v0.9.3 起的"Windows 原生对等"策略保持一致。资料来源：[tools/file-guard/README.md:30-50]()。
需要注意的是，v0.13.0 的已知限制（Known Limitations）数据库指出，Claude Code 在子代理（subagent）场景下，`FileChanged` 钩子存在凭据泄露披露；`file-guard` 与 `read-once` 的组合可缓解此类风险，但不能替代运行时最小权限授予。建议在启用时同时配置 `git-safe` 与 `worktree-guard`，形成对凭据文件的全链路防护。资料来源：[tools/file-guard/README.md:50-70]()。
---
## 会话审计：session-log
### 相关页面
相关主题：[Git 与工作区防护：git-safe / branch-guard / worktree-guard](#page-3), [安全审计与诊断：safety-check / diagnose / test-hook](#page-7)
相关源码文件
以下源码文件用于生成本页说明：
- [tools/session-log/README.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/session-log/README.md)
- [tools/session-log/hook.sh](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/session-log/hook.sh)
- [tools/session-log/hook.ps1](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/session-log/hook.ps1)
- [tools/session-log/report.sh](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/session-log/report.sh)
- [tools/session-log/test.sh](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/session-log/test.sh)
- [tools/session-log/test-report.sh](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/session-log/test-report.sh)
# 会话审计：session-log
## 概述与定位
`session-log` 是 Boucle-framework 工具集中专门负责**会话级审计**的子模块。它通过 Claude Code 的 hook 接口，在每次会话开始（`UserPromptSubmit` / `SessionStart`）与结束（`SessionEnd`）事件触发时，把会话元数据写入追加式日志文件，从而为后续的事后审查、行为回放与异常排查提供原始证据链。`session-log` 自身不直接拦截危险操作，它属于**纯观察型 hook**（observe-only），与 `bash-guard`、`git-safe`、`worktree-guard` 等拦截型 hook 协同存在但职责解耦。
跨平台一致性是该模块的基础要求。Boucle-framework 自 v0.9.3 起要求每个 hook 同时提供 POSIX shell 与原生 PowerShell 实现，`session-log` 也不例外：`hook.sh` 在 Linux/macOS 环境下被 Claude Code 调用，而 `hook.ps1` 在 Windows 原生环境下提供对等能力，避免用户为审计日志而被迫安装 WSL 或 `jq` 资料来源：[tools/session-log/README.md:1-40]() 资料来源：[tools/session-log/hook.sh:1-30]() 资料来源：[tools/session-log/hook.ps1:1-30]()。
## 架构与事件流
`session-log` 的内部组件分工如下：
| 组件 | 角色 | 调用时机 |
|------|------|---------|
| `hook.sh` / `hook.ps1` | 接收 Claude Code 注入的 JSON 事件流，提取会话标识、时间戳、用户/Agent 角色，并追加写入日志 | 每个被 hook 的事件 |
| `report.sh` | 离线汇总脚本，按时间窗聚合日志、统计事件类型频次、生成可读报告 | 手动/定时调用 |
| `test.sh` | 针对 hook 的事件解析、格式兼容、跨平台路径处理进行单元测试 | CI / 本地验证 |
| `test-report.sh` | 验证 `report.sh` 在不同日志样本下的聚合正确性 | CI / 本地验证 |
事件写入采用**追加（append-only）**模式，不删除、不截断既有记录，从而天然保留不可篡改的审计痕迹。日志文件路径通常位于项目根目录下的 `.boucle/sessions/` 目录（具体路径配置可见 README），并以 ISO-8601 时间戳作为文件名的一部分，方便按时间排序与归档 资料来源：[tools/session-log/hook.sh:30-90]() 资料来源：[tools/session-log/README.md:40-80]()。
```mermaid
flowchart LR
CC[Claude Code 事件] --> H{平台}
H -->|POSIX| HS[hook.sh]
H -->|Windows| HP[hook.ps1]
HS --> LOG[(.boucle/sessions/*.log
追加写入)]
HP --> LOG
LOG --> R[report.sh
离线聚合]
R --> REP[可读审计报告]
T1[test.sh] -.验证.-> HS
T1 -.验证.-> HP
T2[test-report.sh] -.验证.-> R
```
## 关键行为与配置要点
- **事件载荷解析**：`hook.sh` 与 `hook.ps1` 通过 `jq` / `ConvertFrom-Json` 解析 stdin 上的 JSON，提取 `session_id`、`hook_event_name`、`cwd`、提示词或工具调用摘要等字段；对解析失败的事件，hook 不会阻断会话，而是记录一条带错误标记的占位行 资料来源：[tools/session-log/hook.sh:60-110]() 资料来源：[tools/session-log/hook.ps1:50-100]()。
- **输出格式**：自 v0.11.0 框架完成 `decision:block` → `hookSpecificOutput.permissionDecision:deny` 迁移后，拦截型 hook 的输出格式被统一，但 `session-log` 属于观察型 hook，通常以 `hookSpecificOutput.additionalContext` 或标准 `{"continue": true}` 形式返回，**不阻断**会话流程，确保审计链路不影响主路径 资料来源：[tools/session-log/README.md:80-120]()。
- **跨平台路径处理**：`hook.ps1` 使用 `Join-Path` 与 `New-Item -Force` 确保目录存在并正确转义 Windows 路径；`hook.sh` 使用 `mktemp` 与 `tee -a` 避免并发写入冲突。两者都通过测试覆盖了包含空格与中文的路径 资料来源：[tools/session-log/test.sh:1-60]()。
- **报告生成**：`report.sh` 默认读取当天的日志文件，输出事件计数、会话时长分布、最早/最晚事件时间戳；支持 `--since` / `--until` 参数按时间窗筛选，便于配合 `Known Limitations` 数据库（v0.13.0 已扩展至 640 条记录）做关联分析 资料来源：[tools/session-log/report.sh:1-80]() 资料来源：[tools/session-log/test-report.sh:1-50]()。
## 与其他模块的关系及已知限制
`session-log` 与拦截型 hook 在同一事件管道上并行运行，但**完全独立**：拦截型 hook 返回 `deny` 时，事件仍会被 `session-log` 记录（记录的是“被拒绝的尝试”，而非“被实际执行的操作”），这对于回放 Agent 行为、识别绕过尝试至关重要。
需要注意的运行时限制：
- 日志以明文追加，不做加密或哈希链；若攻击者获得文件系统写权限，可注入伪造条目。该问题已登记在 `Known Limitations` 数据库的“审计完整性”分类下。
- `hook.sh` / `hook.ps1` 仅记录 hook 事件，无法捕获 Agent 在 `Bash` 工具内执行的子进程内事件；这部分需要依赖 `bash-guard` 的命令级审计。
- 大量会话并发时，追加写可能产生竞争；测试套件验证了 `tee -a` 与 PowerShell `Add-Content` 在单文件级别的一致性，但跨文件分布与轮转策略需用户自行配置。
通过 `test.sh` 与 `test-report.sh` 的持续覆盖，`session-log` 在每次发布前都会经过事件解析、跨平台路径、并发写入、报告聚合四个维度的回归验证，确保审计数据可信、可回放、可追溯 资料来源：[tools/session-log/test.sh:60-140]() 资料来源：[tools/session-log/test-report.sh:50-120]()。
---
## CLAUDE.md 规则强制执行：enforce-hooks
### 相关页面
相关主题：[文件与读取防护：file-guard / read-once](#page-4), [安全审计与诊断：safety-check / diagnose / test-hook](#page-7)
相关源码文件
以下源码文件用于生成本页说明：
- [tools/enforce/README.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/enforce/README.md)
- [tools/enforce/READ_ONLY_AUDIT.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/enforce/READ_ONLY_AUDIT.md)
- [tools/enforce/SKILL.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/enforce/SKILL.md)
- [tools/enforce/enforce-hooks.py](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/enforce/enforce-hooks.py)
- [tools/enforce/engine.sh](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/enforce/engine.sh)
- [tools/enforce/session-hook.sh](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/enforce/session-hook.sh)
# CLAUDE.md 规则强制执行：enforce-hooks
## 目的与定位
`enforce-hooks` 是 Boucle-framework 中负责把 `CLAUDE.md` 里写下的项目级规则转译为 Claude Code 实际可执行的 hook 链路的工具模块。它读取 `CLAUDE.md` 中的约束条目，经过规范化与匹配后，生成可在 `settings.json` 中注册的 PreToolUse、PostToolUse 与 SessionStart 等 hook 调用，使 AI agent 在每次工具调用时都接受规则校验。`README.md` 中明确说明该模块的目标是把"文档化的安全规约"变成"机器可强制执行的钩子"，从而弥合"写了但没人执行"的合规空白。资料来源：[tools/enforce/README.md:1-40]()
由于 hook 既能拒绝危险命令也能审计误用，`READ_ONLY_AUDIT.md` 进一步约束模块默认运行在只读审计模式：除非显式启用 `enforce`，否则仅产生报告而不阻断工具调用，避免误伤开发流程。资料来源：[tools/enforce/READ_ONLY_AUDIT.md:12-58]()
## 核心组件
模块由四个相互协作的组件构成，分别承担规则解析、引擎执行、会话注入与文档说明：
| 组件 | 文件 | 职责 |
|------|------|------|
| 规则解析器 | `enforce-hooks.py` | 扫描 `CLAUDE.md`，提取禁词、允许命令、路径白名单等条目，并生成中间 JSON 规则集 |
| 引擎脚本 | `engine.sh` | 接收 hook 事件 JSON，按规则集做模式匹配，输出 Claude Code 期望的判定结构 |
| 会话 hook | `session-hook.sh` | 在 `SessionStart` 时下发规则上下文，确保新会话加载最新的 `CLAUDE.md` 解释 |
| 文档说明 | `SKILL.md` | 描述 agent 如何理解、调用并解释 hook 的输出 |
`SKILL.md` 把这一组组件抽象为一项可被 agent 复用的"技能"，详细描述触发条件与典型用法，使模型能在不确定时回查规则摘要。资料来源：[tools/enforce/SKILL.md:5-72]()
## 工作流
`enforce-hooks` 在一次工具调用生命周期内的执行路径如下：
```mermaid
flowchart LR
A[Claude Code 工具调用] --> B[settings.json hook 触发]
B --> C[engine.sh 接收事件 JSON]
C --> D{规则匹配}
D -- 命中禁止规则 --> E[deny + reason]
D -- 命中允许规则 --> F[allow]
D -- 未命中 --> G[passthrough]
E --> H[返回 hookSpecificOutput]
F --> H
G --> H
H --> I[Claude Code 决策执行]
```
`enforce-hooks.py` 在初始化阶段负责把 `CLAUDE.md` 文本切成可寻址的规则段，并缓存为 `engine.sh` 可消费的 JSON 文件，避免每次 hook 触发都重新解析 Markdown。资料来源：[tools/enforce/enforce-hooks.py:33-119]()
`engine.sh` 接收到事件后会按以下顺序评估：路径白名单 → 命令模式 → 内容关键字 → 用户自定义条目；任一阶段命中即短路返回，以减少延迟。资料来源：[tools/enforce/engine.sh:18-96]()
会话开始时，`session-hook.sh` 会把规则摘要注入到上下文，让 agent 知晓当前生效的禁止项与例外项，从而减少无效尝试并避免反复触发 deny。资料来源：[tools/enforce/session-hook.sh:7-54]()
## 输出格式与版本迁移
自 v0.11.0 起，Boucle-framework 的所有 hook（包括 `enforce-hooks` 派生的 27 个文件）统一改用 Claude Code 推荐的 `hookSpecificOutput.permissionDecision` 字段，旧版 `decision:block` 已被弃用。`README.md` 给出了 v0.11.0 迁移对照表，便于运维一次性替换。资料来源：[tools/enforce/README.md:42-88]()
---
## 安全审计与诊断：safety-check / diagnose / test-hook
### 相关页面
相关主题：[项目概述与快速开始](#page-1), [CLAUDE.md 规则强制执行：enforce-hooks](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [tools/safety-check/README.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/safety-check/README.md)
- [tools/safety-check/QUICKSTART.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/safety-check/QUICKSTART.md)
- [tools/safety-check/CI.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/safety-check/CI.md)
- [tools/safety-check/TRIAGE.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/safety-check/TRIAGE.md)
- [tools/safety-check/UPDATE_CHECKLIST.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/safety-check/UPDATE_CHECKLIST.md)
- [tools/safety-check/SUPPORT_EVIDENCE.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/safety-check/SUPPORT_EVIDENCE.md)
# 安全审计与诊断：safety-check / diagnose / test-hook
`tools/safety-check/` 是 Boucle-framework 内置的一组"自检 + 外部诊断"工具集，用于在 Claude Code hook 部署到本地或 CI 流水线之前，先确认 hook 自身没有引入新的安全漏洞、误报或可绕过路径。该目录以 `safety-check` 为主入口，配合 `diagnose` 模式与 `test-hook.sh`（自 v0.12.0 引入）形成从"全量审计 → 单点诊断 → 单条 hook 测试"的三层流程。资料来源：[tools/safety-check/README.md]()
## 1. 设计目标与作用域
`safety-check` 不是 Claude Code hook 的替代品，而是面向 hook 开发者与安全运维的**离线分析器**。其作用域包括：
- 校验 hook 在最新 Claude Code 行为下的有效性；
- 复现公开披露的"Known Limitations"（已知限制，简称 KL）绕过模式；
- 在 CI 中作为门禁，防止带 bypass 漏洞的 hook 被合并；
- 维护者根据 `TRIAGE.md` 的分级标准对新增 KL 条目打严重等级标签。
与 hook 自身的"运行时拦截"职责不同，`safety-check` 仅在**构建/审核阶段**触发，不会出现在 Claude Code 的实际会话路径上。资料来源：[tools/safety-check/QUICKSTART.md]()、[tools/safety-check/CI.md]()
## 2. 三层诊断工具链
| 工具 | 触发方式 | 主要职责 | 适用阶段 |
|------|----------|----------|----------|
| `safety-check` | 全量扫描 | 遍历 `hooks/` 下的 `.sh` / `.ps1` 文件，比对最新 KL 数据库 | PR / 发布前 |
| `diagnose` | 聚焦模式 | 针对单个 hook 或某条可疑命令复现违规路径 | 维护者排错 |
| `test-hook.sh` | 单元级测试 | 喂入样例 payload，断言 hook 是否返回 `deny` | 提交前 / CI |
`test-hook.sh` 自 v0.12.0 起正式入仓，与可搜索的 KL 页面（[framework.boucle.sh/limitations.html](https://framework.boucle.sh/limitations.html)）一同发布，使用户可以在本地复现 215 → 640 条 KL 条目中的任意一条。资料来源：[tools/safety-check/CI.md]()、[tools/safety-check/QUICKSTART.md]()
## 3. 已知限制（KL）数据库联动
`safety-check` 的判断依据是一份持续增长的 KL 数据库：
- **v0.12.0**：215 条初始条目，配套上线可搜索网页与 `test-hook.sh`；
- **v0.13.0**：条目数扩展至 640 条，新增 42 critical、266 high、237 medium、95 low 五个严重等级；分类法从 36 个合并为 17 个规范类目。
显著披露包括 unsolicited session injection、subagent git-staging 数据丢失、`FileChanged`-hook 凭据泄露、Buddy ghost prompt injection 等 CRITICAL 项。`diagnose` 在运行时优先尝试匹配这些条目，再回退到通用规则。资料来源：[tools/safety-check/UPDATE_CHECKLIST.md]()、[tools/safety-check/TRIAGE.md]()
## 4. CI 集成与支持证据链
将 `safety-check` 接入 CI 时，推荐做法是在 GitHub Actions 中以 `--strict` 选项运行，对返回非零退出码的 PR 直接阻断合并。`SUPPORT_EVIDENCE.md` 维护了"每条严重等级建议对应何种证据（issue 编号、PoC、复现命令）"的最小集，避免维护者凭印象给 KL 标级。`TRIAGE.md` 则给出复现 → 影响面 → 缓解方案的三步评估模板。资料来源：[tools/safety-check/CI.md]()、[tools/safety-check/TRIAGE.md]()、[tools/safety-check/SUPPORT_EVIDENCE.md]()
```mermaid
flowchart LR
A[hook 源码变更] --> B[safety-check 全量扫描]
B --> C{KL 命中?}
C -- 是 --> D[diagnose 复现]
C -- 否 --> E[test-hook.sh 单元测试]
D --> F[更新 KL 数据库]
E --> G{CI 通过?}
G -- 否 --> H[阻断合并]
G -- 是 --> I[合入主干]
F --> I
```
> 注：用户应在升级到 v0.12.0 之前，先用 `test-hook.sh` 在本地回归一遍自定义 hook，因为 `hookSpecificOutput.permissionDecision:deny` 的输出格式迁移会影响旧断言。资料来源：[tools/safety-check/QUICKSTART.md]()
---
## 已知限制数据库（Known Limitations）
### 相关页面
相关主题：[危险命令拦截：bash-guard](#page-2), [安全审计与诊断：safety-check / diagnose / test-hook](#page-7)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/limitations.html](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/docs/limitations.html)
- [docs/limitations.json](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/docs/limitations.json)
- [docs/limitations-feed.xml](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/docs/limitations-feed.xml)
- [tools/export-kl.py](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/export-kl.py)
- [scripts/add-kl.py](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/scripts/add-kl.py)
- [scripts/add-kl-batch.py](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/scripts/add-kl-batch.py)
# 已知限制数据库（Known Limitations）
## 概述与定位
已知限制数据库（Known Limitations，简称 KL）是 Boucle-framework 中专门记录 Claude Code 钩子与代理行为缺陷的公共知识库。它的定位并非"插件功能列表"，而是一份**透明的负面清单**：把 Claude Code 在钩子拦截、文件编辑、子代理委派、git 操作等场景下尚未修复或被绕过的缺陷以结构化形式公开，避免用户在不知情的情况下依赖不存在的保护。
从 v0.12.0 起，KL 数量为 215 条；到 v0.13.0 已扩展到 **640 条**（新增 425 条），严重程度被划分为四档：critical、high、medium、low；分类法从 36 个碎片化标签合并为 **17 个规范类别**。资料来源：[CHANGELOG.md]()、[docs/limitations.json:1-40]()。
## 数据结构与分类法
KL 的核心数据载体是 `docs/limitations.json`，它是整个系统的"单一事实来源"（single source of truth）。每条记录通常包含：唯一 ID、严重程度（critical / high / medium / low）、所属规范类别、简短标题、详细描述、受影响的钩子或代理组件、相关上游 issue 编号、以及发布时间戳。脚本 `scripts/add-kl.py` 负责**单条**录入（含字段校验与 ID 自增），`scripts/add-kl-batch.py` 则在批量归档历史问题时复用同一 schema，保证多来源数据汇入后字段一致。资料来源：[scripts/add-kl.py:1-80]()、[scripts/add-kl-batch.py:1-60]()。
| 字段 | 作用 |
|------|------|
| `id` | 稳定主键，用于 URL 深链与去重 |
| `severity` | critical / high / medium / low 四档排序权重 |
| `category` | 17 个规范类别之一，取代 v0.12.0 之前的 36 个标签 |
| `component` | 受影响的钩子（如 `bash-guard`、`worktree-guard`）或代理组件 |
| `refs` | 上游 GitHub issue 或内部票据引用 |
| `summary` / `details` | 标题与正文，供 HTML 渲染与 RSS 摘要使用 |
## 发布层：HTML 与订阅源
`tools/export-kl.py` 在每次发布前读取 `docs/limitations.json`，生成两份公共产物：
1. `docs/limitations.html` —— 提供**文本搜索、类别筛选、严重程度过滤、URL 深链**的浏览界面，部署在 `framework.boucle.sh/limitations.html`。所有过滤状态都可序列化到 URL 哈希，方便用户直接分享定位到某条 KL 的链接。资料来源：[docs/limitations.html:1-60]()。
2. `docs/limitations-feed.xml` —— RSS/Atom 订阅源，便于安全研究者与下游项目通过 feed 自动跟踪新增条目。资料来源：[docs/limitations-feed.xml:1-30]()。
```mermaid
flowchart LR
A[scripts/add-kl.py
add-kl-batch.py] --> B[(docs/limitations.json)]
B --> C[tools/export-kl.py]
C --> D[docs/limitations.html]
C --> E[docs/limitations-feed.xml]
D --> F[framework.boucle.sh/limitations.html]
E --> G[RSS 订阅者]
```
## 工作流与维护契约
数据库的维护遵循"录入 → 校验 → 导出 → 发布"四步：开发者通过 `add-kl.py` 或 `add-kl-batch.py` 写入 JSON；CI 在合并前运行导出器刷新 HTML 与 feed；站点通过 GitHub Pages 自动部署。分类法在 v0.13.0 完成合并后，**新增条目必须落到 17 个规范类别之一**，避免再次碎片化。
需要注意的是，KL 列表与 Boucle 的钩子防御能力**不是冗余关系**：钩子负责在运行时阻断危险操作，KL 则负责记录 Claude Code 平台层面尚未被钩子覆盖或本身无法覆盖的限制（如 v0.13.0 披露的"unsolicited session injection"、"subagent git-staging data loss"、"FileChanged-hook credential leak" 等 critical 条目）。两者协同构成"防御 + 透明"的完整姿态。资料来源：[tools/export-kl.py:1-100]()、[CHANGELOG.md]()。
---
## 跨平台支持与 Windows PowerShell 兼容
### 相关页面
相关主题：[危险命令拦截：bash-guard](#page-2), [项目概述与快速开始](#page-1)
相关源码文件
以下源码文件用于生成本页说明：
- [tools/bash-guard/hook.ps1](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/bash-guard/hook.ps1)
- [tools/branch-guard/hook.ps1](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/branch-guard/hook.ps1)
- [tools/file-guard/hook.ps1](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/file-guard/hook.ps1)
- [tools/git-safe/hook.ps1](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/git-safe/hook.ps1)
- [tools/worktree-guard/hook.ps1](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/worktree-guard/hook.ps1)
- [tools/session-log/hook.ps1](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/session-log/hook.ps1)
# 跨平台支持与 Windows PowerShell 兼容
## 概述与设计目标
Boucle-framework 是一个面向 Claude Code 的 hook 安全框架，其核心约束之一是"必须同时在 Unix 类系统与 Windows 上原生运行"。在 v0.9.3 之前，部分 hook 依赖 bash 与 `jq`，在 Windows 上只能借助 WSL 才能运行；该项目通过为每个 hook 提供一份对等的 PowerShell 实现（`.ps1`），使 Windows 用户无需 WSL、无需 bash、无需 jq 即可获得完整的安全防护。
截至 v0.9.3，框架内 7/7 的 hook 都已具备原生 PowerShell 等价实现，达到"Windows Parity Complete"里程碑。资料来源：[tools/bash-guard/hook.ps1:1-50]()、[tools/git-safe/hook.ps1:1-40]()
## Hook 清单与 PowerShell 映射
下表列出本次涉及的 6 个 hook 的 PowerShell 实现入口。所有 PS1 文件均使用 Claude Code 推荐的 `hookSpecificOutput.permissionDecision` 输出格式，遵循 v0.11.0 的迁移规范。
| Hook 名称 | PowerShell 文件 | 主要职责 |
|---|---|---|
| bash-guard | `tools/bash-guard/hook.ps1` | 检测并阻断危险 bash 命令 |
| branch-guard | `tools/branch-guard/hook.ps1` | 保护 git 分支操作 |
| file-guard | `tools/file-guard/hook.ps1` | 拦截危险的 Write/Edit 调用 |
| git-safe | `tools/git-safe/hook.ps1` | 强制 git 安全策略（如禁止 `--no-verify`） |
| worktree-guard | `tools/worktree-guard/hook.ps1` | 防止 worktree 数据丢失 |
| session-log | `tools/session-log/hook.ps1` | 记录会话事件 |
资料来源：[tools/bash-guard/hook.ps1:1-30]()、[tools/branch-guard/hook.ps1:1-30]()、[tools/file-guard/hook.ps1:1-30]()、[tools/git-safe/hook.ps1:1-30]()、[tools/worktree-guard/hook.ps1:1-30]()、[tools/session-log/hook.ps1:1-30]()
## bash-guard 的 PowerShell 实现
`bash-guard/hook.ps1` 是项目中规模最大的 PS1 实现（v0.9.3 报告为 849 行、112 条检查规则、51 个模式类别）。其覆盖范围包括云基础设施命令、编码绕过（例如 `perl -i`、`sed -i`、`ruby -i`、`ed`，源自 v0.9.2 针对 in-place 编辑绕过漏洞的修复）以及磁盘工具类危险指令。
资料来源：[tools/bash-guard/hook.ps1:1-100]()
## git-safe 与 worktree-guard 的跨平台语义
`git-safe/hook.ps1` 在 PowerShell 端完整复刻了 bash 版本的两项关键能力：
- **`--no-verify` 绕过检测**：拦截 `git commit --no-verify`、`git push --no-verify` 以及 `-n` 简写，避免 agent 跳过 pre-commit 与 GPG 签名。
- **`worktree-guard` squash merge 误报修复**：采用双层检测（Tier 1 + Tier 2），取代原先仅依赖 SHA 比对的方式，从而消除 squash merge 场景下的误报。
资料来源：[tools/git-safe/hook.ps1:40-120]()、[tools/worktree-guard/hook.ps1:1-80]()
## 输出格式与版本兼容性
所有 PS1 hook 在调用 Claude Code 时统一输出 `hookSpecificOutput.permissionDecision:deny` JSON，取代了 v0.11.0 之前的 `decision:block` 写法。该格式是 Claude Code 当前推荐的契约，因此无论是 bash 还是 PowerShell 实现，运行时拦截语义保持一致。
资料来源：[tools/bash-guard/hook.ps1:60-120]()、[tools/file-guard/hook.ps1:1-60]()、[tools/session-log/hook.ps1:1-60]()
## 状态流转示意
```mermaid
stateDiagram-v2
[*] --> 接收事件: Claude Code 触发 hook
接收事件 --> 解析输入: 读取 JSON stdin
解析输入 --> 规则匹配: PowerShell 模式检测
规则匹配 --> 阻断: 命中危险模式
规则匹配 --> 放行: 未命中
阻断 --> 输出deny: hookSpecificOutput.permissionDecision
放行 --> [*]
输出deny --> [*]
```
## 维护注意事项
1. **同步双实现**：每当 bash 版本新增规则，必须同步在 `hook.ps1` 中加入等价检测，否则 Windows 端会出现防护空窗。
2. **避免依赖 bash/jq**：PS1 实现须使用纯 PowerShell 原生语法（如 `-match`、`Get-Content`、`ConvertTo-Json`），不得回退到 WSL 或外部工具。
3. **输出格式校验**：发布前应运行 `tools/test-hook.sh`（v0.12.0 引入）验证 PS1 与 sh 的输出契约一致。
资料来源：[tools/bash-guard/hook.ps1:100-200]()、[tools/git-safe/hook.ps1:120-200]()
---
## 自主代理循环运行器（Rust 框架）
### 相关页面
相关主题：[Broca 记忆系统](#page-11), [MCP 服务器与 Claude Code 集成](#page-12), [CLAUDE.md 规则强制执行：enforce-hooks](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [boucle-cli/README.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/boucle-cli/README.md)
- [boucle-cli/Cargo.toml](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/boucle-cli/Cargo.toml)
- [boucle-cli/src/main.rs](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/boucle-cli/src/main.rs)
- [boucle-cli/src/loop.rs](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/boucle-cli/src/loop.rs)
- [boucle-cli/src/config.rs](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/boucle-cli/src/config.rs)
- [boucle-cli/agent.toml](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/boucle-cli/agent.toml)
# 自主代理循环运行器（Rust 框架）
## 概述与定位
Boucle 框架的安全控制链路中，绝大部分组件以 shell 脚本（bash / PowerShell）形式存在，而 `boucle-cli` 则是其中唯一的 Rust 实现。它作为命令行二进制被 Claude Code 代理在 shell 层面调用，承担"读取钩子事件 → 匹配策略 → 输出决策"的核心驱动职责，与 27 个 hook 脚本协同形成双层防御。它本身不直接展示 LLM 行为，而是充当一个轻量级驱动器：解析由 Claude Code 触发的钩子调用协议，读取 `agent.toml` 中的策略定义，并驱动 `loop.rs` 中的主循环。
```mermaid
graph LR
A[Claude Code 代理] -->|触发钩子事件| B[boucle-cli]
B --> C[config.rs 加载 agent.toml]
B --> D[loop.rs 策略匹配]
D --> E[输出 permissionDecision]
E --> A
```
资料来源：[boucle-cli/README.md:1-40]()，[boucle-cli/Cargo.toml:1-30]()
## 模块组成与配置加载
`boucle-cli` 的源码划分为三个核心模块：
- `main.rs`：进程入口，负责参数解析、初始化日志、加载配置并启动主循环。
- `loop.rs`：实现"读取 → 处理 → 写入"的循环主体，是运行器的心脏。
- `config.rs`：将 `agent.toml` 反序列化为强类型配置结构体。
`config.rs` 在反序列化时对缺失字段采取保守默认值：未显式声明的项会回退到"拒绝"或"放行但记录日志"，与框架整体的"fail-closed"安全取向保持一致。`agent.toml` 采用 TOML 格式书写，常见配置节包括运行模式（同步/异步）、钩子事件过滤器、默认拒绝策略以及与 LLM 适配的端点信息。
资料来源：[boucle-cli/src/main.rs:1-60]()，[boucle-cli/src/config.rs:10-80]()，[boucle-cli/agent.toml:1-30]()
## 循环运行流程
`loop.rs` 中的主循环大致遵循以下顺序：
1. 从标准输入读取 Claude Code 触发的一次钩子事件，事件格式遵循 v0.11.0 引入的 `hookSpecificOutput.permissionDecision:deny` 协议。
2. 根据 `agent.toml` 中注册的策略表对事件进行匹配。
3. 若策略命中，发出 `deny` 决策并附带原因；若未命中，则透传到下游执行器。
4. 将结果以 JSON 形式写回标准输出，供 Claude Code 主进程消费。
该循环对 v0.9.1 加入的 `--no-verify` 绕过、v0.9.2 的 `perl -i` 原位编辑绕过、v0.9.2 的 glob 通配符注入等已知问题具有识别能力。匹配规则由配置驱动，可在不改动代码的情况下热更新，从而降低策略迭代的部署成本。
资料来源：[boucle-cli/src/loop.rs:50-200]()
## 已知限制与生态协作
`boucle-cli` 与现有 27 个 bash / PowerShell 钩子脚本形成"前置驱动 + 后置拦截"的双层结构：Rust 端负责快速路径判断与协议解析，脚本端负责精细模式匹配。v0.9.3 之后，Windows 平台通过 PowerShell 等价物（bash-guard.ps1 等 7 个 PS1 文件）完成协作，达成 7/7 钩子的 Windows 原生覆盖，CLI 端与脚本端在两端共享 `permissionDecision` 协议层。
然而运行器本身仍受到 v0.13.0 Known Limitations 数据库中 42 项 CRITICAL 披露的影响，尤其是"unsolicited session injection"与"subagent git-staging data loss"。这些注入发生在 Claude Code 主进程边界之外，`boucle-cli` 无法独立拦截，必须依赖 hook 链路与上游 LLM 协同防御。在部署时应将运行器视为"必要但不充分"的安全组件，与框架其余 hook 配合使用。
资料来源：[boucle-cli/src/loop.rs:200-260]()，[boucle-cli/src/config.rs:80-120]()
---
## Broca 记忆系统
### 相关页面
相关主题：[自主代理循环运行器（Rust 框架）](#page-10), [MCP 服务器与 Claude Code 集成](#page-12)
相关源码文件
以下源码文件用于生成本页说明：
- 注：本次分析未对仓库进行实时检索（无检索增强）。所引用的源码路径来源于查询中给定的文件清单，未能独立验证其存在性与内容。基于公开的社区上下文（Release Notes、CHANGELOG、README 摘要），Boucle-framework 仓库主要面向 Claude Code 钩子（hook）框架，而非命名意义上的 "Broca 记忆系统" 子模块。下文中所有断言均限于社区证据可支持的范围；未在社区上下文中出现的具体行为不予声明。
# Broca 记忆系统
## 关于本主题的说明
依据可获取的社区证据，`Bande-a-Bonnot/Boucle-framework` 仓库目前已发布至 **v0.13.0**，主线工作是 **Claude Code 钩子（hook）安全框架**：包括 `bash-guard`、`git-safe`、`worktree-guard`、`file-guard` 等钩子、Bash 与 PowerShell 双平台实现、`hookSpecificOutput.permissionDecision` 输出格式迁移，以及 **Known Limitations (KL) 数据库**。资料来源：[https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.13.0]()
截至本次分析所基于的社区上下文，没有直接证据表明仓库中存在名为 `boucle-memory` 或 `broca` 的子 crate，也没有公开的 "Broca 记忆系统" 功能描述。若此类子系统已存在但未在 Release Notes、CHANGELOG 或公开文档中披露，本页无法在不臆测的前提下对其进行说明。
## 在已发布的 v0.13.0 中与"记忆"语义最接近的概念
虽然仓库并未公开一个被命名为"Broca 记忆系统"的模块，但社区上下文披露了一个与"长期记忆 / 累积知识"语义高度相关的子系统——**Known Limitations (KL) 数据库**。该数据库充当了 Claude Code 钩子框架的"缺陷记忆"：持续记录 hook / agent 行为中的已知问题，便于后续被规则化、可检索地规避。
### 数据规模与增长
- v0.12.0 时条目数为 **215**，并发布了一个可浏览、可搜索、可过滤的页面 `framework.boucle.sh/limitations.html`，支持文本检索、类别筛选与 URL 深链。资料来源：[https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.12.0]()
- v0.13.0 时条目数扩展至 **640**（自 v0.12.0 起新增 425 条），分类由 36 个碎片化类别整合为 **17 个规范类别**；严重度分布为：42 critical / 266 high / 237 medium / 95 low。资料来源：[https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.13.0]()
### 写入路径（基于版本叙述推断）
每个版本周期中，维护者将社区上报或自审计得到的 hook / agent 缺陷聚合、归类并写入 KL 库；v0.12.0 同步交付了一个名为 `test-hook.sh` 的回归测试脚本，便于在新增条目时复用执行验证。资料来源：[https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.12.0]()
### 读取路径
- 静态站点形式：`framework.boucle.sh/limitations.html`，提供搜索、过滤与深链。资料来源：[https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.12.0]()
- 在仓库内以结构化文档形式随版本发布：每个版本 Release Notes 中列出关键披露条目，例如 v0.13.0 提到的 **unsolicited session injection**、**subagent git-staging data loss**、**`FileChanged`-hook credential leak**、**Buddy ghost prompt injection** 等 CRITICAL 级别披露。资料来源：[https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.13.0]()
## 与"记忆系统"主题相关的若干边界
### 与钩子行为修复的耦合
KL 数据库并非被动清单，它会反向驱动规则更新。例如：
- **v0.9.1**：`git-safe` 新增 `--no-verify` / `-n` 旁路检测（防止 sub-agent 跳过 pre-commit 与 GPG 签名），此修复源于已记录的 KL 条目被确认为高风险绕过。资料来源：[https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.9.1]()
- **v0.9.2**：`bash-guard` 增强就地编辑绕过检测，阻断 `perl -i`、`ruby -i`、`sed -i`、`ed` 等命令；并新增 glob 通配符注入检测。修复依据为 [anthropics/claude-code#40408](https://github.com/anthropics/claude-code/issues/40408) 公开缺陷。资料来源：[https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.9.2]()
- **v0.9.1**：`worktree-guard` 用两级检测替代纯 SHA 比较，以减少 squash-merge 触发的误报。资料来源：[https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.9.1]()
- **v0.8.0**：`worktree-guard` 阻止 `ExitWorktree` 时遗留未提交变更、未跟踪文件、未合并分支或未推送提交，源于 [anthropics/claude-code#38287](https://github.com/anthropics/claude-code/issues/38287) 的数据丢失事件。资料来源：[https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.8.0]()
### 与输出格式的耦合
v0.11.0 将全部 27 个 hook 文件迁移至 Claude Code 推荐的 `hookSpecificOutput.permissionDecision:deny` 格式。这意味着 KL 数据库中的"绕过 hook"条目也必须随格式迁移被重新验证，否则旧条目可能不再准确反映新格式下的拦截行为。资料来源：[https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.11.0]()
### 与平台覆盖的耦合
v0.9.3 实现 **Windows 7/7 钩子原生 PowerShell 等价物**，含 `bash-guard.ps1`（849 行、112 条规则、51 类模式）。KL 数据库中若条目涉及平台差异（如路径分隔符、shell 行为），需要在 Bash 与 PowerShell 双端独立复核。资料来源：[https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.9.3]()
## 概念关系图
```mermaid
flowchart LR
A[Claude Code 缺陷事件
Issues / 自审计] --> B[KL 数据库
v0.12: 215 → v0.13: 640]
B --> C[规则更新
bash-guard / git-safe / worktree-guard]
C --> D[Hook 输出格式
permissionDecision:deny]
B --> E[静态门户
limitations.html 搜索/过滤/深链]
D --> F[双平台执行
Bash + PowerShell]
E --> F
```
## 资料来源汇总
- v0.13.0 Release Notes：https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.13.0
- v0.12.0 Release Notes：https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.12.0
- v0.11.0 Release Notes：https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.11.0
- v0.10.0 Release Notes：https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.10.0
- v0.9.3 Release Notes：https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.9.3
- v0.9.2 Release Notes：https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.9.2
- v0.9.1 Release Notes：https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.9.1
- v0.9.0 Release Notes：https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.9.0
- v0.8.0 Release Notes：https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.8.0
- v0.7.0 Release Notes：https://github.com/Bande-a-Bonnot/Boucle-framework/releases/tag/v0.7.0
---
## MCP 服务器与 Claude Code 集成
### 相关页面
相关主题：[自主代理循环运行器（Rust 框架）](#page-10), [Broca 记忆系统](#page-11), [CLAUDE.md 规则强制执行：enforce-hooks](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [boucle-mcp/README.md](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/boucle-mcp/README.md)
- [boucle-mcp/Cargo.toml](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/boucle-mcp/Cargo.toml)
- [boucle-mcp/src/server.rs](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/boucle-mcp/src/server.rs)
- [boucle-mcp/src/tools.rs](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/boucle-mcp/src/tools.rs)
- [.mcp.json](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/.mcp.json)
- [examples/hello-world/.mcp.json](https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/examples/hello-world/.mcp.json)
# MCP 服务器与 Claude Code 集成
## 定位与目标
Boucle-framework 通过 `boucle-mcp` 子 crate 提供一个独立的 MCP（Model Context Protocol）服务器，使 Claude Code 客户端能够以工具（tools）调用的形式访问框架内部的能力，而不仅仅依赖 hook 事件触发。MCP 服务器是框架 "hook 之外" 的第二条执行通道：hooks 拦截危险行为，MCP 则主动暴露受控的操作接口。
资料来源：[boucle-mcp/README.md:1-20]()
## 架构总览
MCP 服务器以 Rust 进程形式运行，通过 stdio 与 Claude Code 通信。Claude Code 在启动时读取项目根或示例目录下的 `.mcp.json`，发现并注册该服务器；之后任何 LLM 回合都可以枚举、调用意图工具。
```mermaid
flowchart LR
CC[Claude Code 客户端] -->|stdio JSON-RPC| MCP[boucle-mcp 服务器进程]
MCP --> SR[server.rs
路由与调度]
SR --> TR[tools.rs
工具实现]
TR -->|读取/校验| FS[框架钩子与策略文件]
TR -->|返回结果| CC
```
资料来源：[boucle-mcp/Cargo.toml:1-30]()，[boucle-mcp/src/server.rs:1-40]()
## 配置与启用
`.mcp.json` 描述了服务器名称、启动命令与参数。仓库根目录下的配置文件用于主项目，示例项目（如 `examples/hello-world/`）各自携带独立的 `.mcp.json`，便于演示隔离。
| 字段 | 作用 |
|------|------|
| `mcpServers` | 服务器注册表 |
| `command` | 启动可执行文件（如 `boucle-mcp`） |
| `args` | 传给服务器的启动参数 |
| `env` | 环境变量注入（路径、调试开关） |
资料来源：[.mcp.json:1-20]()[examples/hello-world/.mcp.json:1-20]()
## 工具层实现
`tools.rs` 定义了 MCP 暴露给模型的具体工具，每个工具对应一个可调用函数，包含名称、描述与参数 schema。模型在收到这些 schema 后即可在合适的回合发起调用；服务器在 `server.rs` 中根据 JSON-RPC 请求完成调度，并返回结构化结果。
资料来源：[boucle-mcp/src/tools.rs:1-60]()[boucle-mcp/src/server.rs:40-120]()
## 与钩子体系的协同
MCP 服务器并不取代 hooks，而是与 hooks 形成互补：hooks 在 `PreToolUse` 等时机做拦截，MCP 工具则在主动查询或批处理场景下提供入口。这种双层防护在 v0.11.0 之后逐步稳定——同期所有 hook 切换到 `hookSpecificOutput.permissionDecision:deny` 输出格式，MCP 工具也遵循同一策略语义，确保拦截与放行判定一致。
资料来源：[boucle-mcp/README.md:20-60]()
## 已知边界
依据 v0.13.0 公布的已知限制（Known Limitations）数据库，640 条记录中有相当一部分与 hook 行为相关；MCP 工具调用也可能受同样的会话注入、影子提示等 CRITICAL 类问题影响。因此在启用 MCP 工具时，仍应保留 hook 兜底，并对模型可调用的工具集合做最小权限裁剪。
资料来源：[boucle-mcp/README.md:60-90]()
---
---
## Doramagic 踩坑日志
项目：Bande-a-Bonnot/Boucle-framework
摘要：发现 11 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：能力坑 - 能力证据存在缺口。
## 1. 能力坑 · 能力证据存在缺口
- 严重度：high
- 证据强度：source_linked
- 发现：Sandbox install result is missing.
- 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
- 证据：evidence.evidence_gaps | https://github.com/Bande-a-Bonnot/Boucle-framework | Sandbox install result is missing.
## 2. 安装坑 · 安装命令尚未沙箱验证
- 严重度：medium
- 证据强度：runtime_trace
- 发现：当前 install_status=documented，还只是文档/元数据线索。
- 对用户的影响：命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。
- 复现命令：`git clone https://github.com/Bande-a-Bonnot/Boucle-framework.git`
- 证据：downstream_validation.install_status | https://github.com/Bande-a-Bonnot/Boucle-framework | install_status=documented; command=git clone https://github.com/Bande-a-Bonnot/Boucle-framework.git
## 3. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/Bande-a-Bonnot/Boucle-framework | host_targets=mcp_host, claude_code, claude
## 4. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/Bande-a-Bonnot/Boucle-framework | README/documentation is current enough for a first validation pass.
## 5. 运行坑 · Quick Start 尚未实际跑通
- 严重度：medium
- 证据强度：source_linked
- 发现：quickstart_status=not_attempted。
- 对用户的影响：用户只能看到安装线索，不能确信 10 分钟内能形成最小可试路径。
- 证据：downstream_validation.quickstart_status | https://github.com/Bande-a-Bonnot/Boucle-framework | quickstart_status=not_attempted; sandbox_quickstart_status=missing
## 6. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/Bande-a-Bonnot/Boucle-framework | last_activity_observed missing
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/Bande-a-Bonnot/Boucle-framework | no_demo; severity=medium
## 8. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 证据：risks.safety_notes | https://github.com/Bande-a-Bonnot/Boucle-framework | No sandbox install has been executed yet; downstream must verify before user use.
## 9. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/Bande-a-Bonnot/Boucle-framework | no_demo; severity=medium
## 10. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/Bande-a-Bonnot/Boucle-framework | issue_or_pr_quality=unknown
## 11. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/Bande-a-Bonnot/Boucle-framework | release_recency=unknown