一、项目定位与目标

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

二、核心能力概览

上表中“已知限制数据库”条目与 v0.12.0 引入的可搜索限制页面、v0.13.0 扩充至 640 条相对应；正面能力（防御钩子）则与 v0.8.0 ~ v0.9.3 系列发布同步演进。资料来源：README.md:30-120

三、跨平台安装（快速开始）

框架遵循“同一逻辑，平台原生分发”原则，在 Linux / macOS 与 Windows 上分别提供独立安装脚本，无需 WSL 或额外模拟层。

Linux / macOS

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 原生）

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 是 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 揭示 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

跨平台实现与格式迁移

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

Boucle-framework 围绕 Claude Code 的 PreToolUse / PreExit 钩子机制，提供了三类针对 Git 与工作区的防护工具。它们通过拦截危险命令与生命周期事件，避免 AI 代理在代码提交、分支操作和工作树切换时引入数据丢失、绕权执行或未经审查的状态变更。该模块属于 v0.13.0 中的「已知限制数据库（Known Limitations）」所覆盖的核心防御面，并在历次版本中持续扩展检测规则。

防护体系总览

三个钩子在 Claude Code 调用栈中的位置互补：

所有钩子均提供 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。

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 是 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。

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。

集成模式与已知约束

两个工具均依赖 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 是 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 的内部组件分工如下：

事件写入采用追加（append-only）模式，不删除、不截断既有记录，从而天然保留不可篡改的审计痕迹。日志文件路径通常位于项目根目录下的 .boucle/sessions/ 目录（具体路径配置可见 README），并以 ISO-8601 时间戳作为文件名的一部分，方便按时间排序与归档 资料来源：tools/session-log/hook.sh:30-90 资料来源：tools/session-log/README.md:40-80。

flowchart LR
    CC[Claude Code 事件] --> H{平台}
    H -->|POSIX| HS[hook.sh]
    H -->|Windows| HP[hook.ps1]
    HS --> LOG[(.boucle/sessions/*.log<br/>追加写入)]
    HP --> LOG
    LOG --> R[report.sh<br/>离线聚合]
    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。

目的与定位

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

核心组件

模块由四个相互协作的组件构成，分别承担规则解析、引擎执行、会话注入与文档说明：

SKILL.md 把这一组组件抽象为一项可被 agent 复用的"技能"，详细描述触发条件与典型用法，使模型能在不确定时回查规则摘要。资料来源：tools/enforce/SKILL.md:5-72

工作流

enforce-hooks 在一次工具调用生命周期内的执行路径如下：

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

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. 三层诊断工具链

test-hook.sh 自 v0.12.0 起正式入仓，与可搜索的 KL 页面（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

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，简称 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。

发布层：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。

flowchart LR
  A[scripts/add-kl.py<br>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。

概述与设计目标

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 的迁移规范。

资料来源：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

状态流转示意

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

概述与定位

Boucle 框架的安全控制链路中，绝大部分组件以 shell 脚本（bash / PowerShell）形式存在，而 boucle-cli 则是其中唯一的 Rust 实现。它作为命令行二进制被 Claude Code 代理在 shell 层面调用，承担"读取钩子事件 → 匹配策略 → 输出决策"的核心驱动职责，与 27 个 hook 脚本协同形成双层防御。它本身不直接展示 LLM 行为，而是充当一个轻量级驱动器：解析由 Claude Code 触发的钩子调用协议，读取 agent.toml 中的策略定义，并驱动 loop.rs 中的主循环。

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

关于本主题的说明

依据可获取的社区证据，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/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/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

概念关系图

flowchart LR
  A[Claude Code 缺陷事件<br/>Issues / 自审计] --> B[KL 数据库<br/>v0.12: 215 → v0.13: 640]
  B --> C[规则更新<br/>bash-guard / git-safe / worktree-guard]
  C --> D[Hook 输出格式<br/>permissionDecision:deny]
  B --> E[静态门户<br/>limitations.html 搜索/过滤/深链]
  D --> F[双平台执行<br/>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

定位与目标

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 回合都可以枚举、调用意图工具。

flowchart LR
  CC[Claude Code 客户端] -->|stdio JSON-RPC| MCP[boucle-mcp 服务器进程]
  MCP --> SR[server.rs<br/>路由与调度]
  SR --> TR[tools.rs<br/>工具实现]
  TR -->|读取/校验| FS[框架钩子与策略文件]
  TR -->|返回结果| CC

资料来源：boucle-mcp/Cargo.toml:1-30，boucle-mcp/src/server.rs:1-40

配置与启用

.mcp.json 描述了服务器名称、启动命令与参数。仓库根目录下的配置文件用于主项目，示例项目（如 examples/hello-world/）各自携带独立的 .mcp.json，便于演示隔离。

资料来源：.mcp.json:1-20examples/hello-world/.mcp.json:1-20

工具层实现

tools.rs 定义了 MCP 暴露给模型的具体工具，每个工具对应一个可调用函数，包含名称、描述与参数 schema。模型在收到这些 schema 后即可在合适的回合发起调用；服务器在 server.rs 中根据 JSON-RPC 请求完成调度，并返回结构化结果。

资料来源：boucle-mcp/src/tools.rs:1-60boucle-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

Pitfall Log / 踩坑日志

项目：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