aelithias/loopgate

# Loopgate [](https://github.com/aelithias/loopgate/actions/workflows/test.yml) [](https://github.com/aelithias/loopgate/actions/workflows/codeql.yml) [](https://github.com/aelithias/loopgate/actions/workflows/govulncheck.yml) [](./LICENSE) **最后更新：** 2026-06-25 **Loopgate** 是一个面向 AI 辅助工程工作的本地优先权限边界。 它在 AI 运行框架与其可调用的工具之间，建立了**已签名的策略**、**显式的审批**以及一个**只追加的本地审计账本**。 当前运行框架重点关注：**Claude Code + 项目 hooks + Loopgate** ## 设计理念 如果您是在评估 Loopgate 背后的设计思想，而不是直接安装它， 请从这里开始： - [理念：看重权限，而非花言巧语](./docs/design_overview/philosophy.md) — 为什么自然语言永远不能凭空产生权限，以及为什么控制平面是 创建、限制和消耗能力的唯一场所 - [威胁模型](./docs/loopgate-threat-model.md) — Loopgate 旨在容纳的 信任边界和故障模式 - [Agent 目录策略（设计草案）](./docs/design_overview/agent_directory_policy_v0.md) — 策略继承方向，使用 Active Directory / 组策略作为类比， 为 Agent 角色分配受限能力，同时不让 编排层授予自身权限 本 README 的其余部分是面向运维人员的设置指南。上面的链接是 了解其概念设计的最快捷径。 ## Loopgate 能为您提供什么 AI 编程工具往往会促使运维人员做出两种糟糕的选择： - 一次又一次地批准相同的低风险操作，直到审批变成 橡皮图章（走过场） - 授予宽泛的隐式访问权限，并期望模型能安分守己 Loopgate 提供了折中之策。它将重复的权限提示转化为明确的 策略： - 例行的低风险工作可以被允许并进行审计 - 较高风险的工作可以要求运维人员进行真正的审批 - 被禁止的工具、路径、站点和操作可以被确定性地拒绝 - 重要操作会留下本地审计追踪记录，供日后检查 对于个人开发者而言，这意味着在减少看护工作的同时，依然能为 写入操作、shell 命令和其他风险操作保留真实的边界。 对于企业或具备安全意识的团队，这是构建管理界面的 基础：签名策略、审批审查、审计检查、hook 状态，以及 最终在受管理的 AI 工具生态中实现更广泛的策略和访问控制。目前 该代码库仍然是本地优先和单节点的；远程集群管理是一个 未来的发展方向，而非目前交付的保证。 ## 状态 Loopgate 目前是： - 实验性的 - 对安全高度敏感的 - 本地优先的 - 专注于治理的 - 在其实现和文档编写中大量依赖 AI 辅助的 请审慎对待此代码库：以对待 AI 生成代码同样的怀疑态度来审查变更， 重测试和确凿证据而轻声明， 不要将流畅的解释或看似自动生成的结构视为正确性的证明。项目的 目标依然是严谨的工程实践，但其来源的背景对于运维人员和贡献者 如何评估它至关重要。 Loopgate **目前还不是**： - 稳定的兼容性目标 - 打包好的桌面产品 - 基于浏览器的管理 UI - 多运行框架平台 - 集中式企业策略服务器 ## 目标受众 Loopgate 面向有以下需求的工程师和具备安全意识的运维人员： - 针对 AI 工具使用，实现确定性的允许 / 审批 / 拒绝行为 - 减少基于提示的看护工作和橡皮图章式的审批 - 获取关于 Agent 实际操作的持久本地记录 - 建立真正的权限边界，而不是将聊天文本伪装成策略 - 迈向企业级 AI 工具策略，同时不将聊天客户端 视为控制平面 ## 目前您可以做什么 当前的产品范围被有意收窄： - 在工具执行前治理 Claude Code hooks - 对较高风险的操作要求审批 - 允许低风险操作并附带审计 - 保持策略的本地签名 - 检查持久化的本地审计账本 - 使用仓库本地的运维 CLI 进行设置、查看状态、冒烟测试和卸载 目前的管理界面以 CLI 为主。计划在相同的 Loopgate 权限 API 之上构建一个控制台 TUI 作为运维操作界面；它绝不能成为 单独的审批或策略事实来源。 引导式的首次运行路径会引导运维人员选择三种初始配置： - `balanced` - `strict` - `read-only` 当前的产品契约在这里： - [Loopgate V1 产品契约](./docs/loopgate_v1_product_contract.md) ## 快速开始 现在有两种实用方式可以体验 Loopgate： - 无需 Go 环境的已发布 macOS 发行版安装 - 获取源码并通过 `make quickstart` 运行 目前发布的安装路径主要针对 macOS 发行版归档。 Linux 目前仍以源码优先，并处于实验阶段。 无 Go 工具链的最快路径： ``` curl -fsSL https://raw.githubusercontent.com/aelithias/loopgate/main/scripts/install.sh | sh loopgate setup loopgate status loopgate test ``` 安装程序会为您的 macOS 架构下载最新发布的发行版归档，将带有版本号的二进制文件安装到 `~/.local/share/loopgate/versions/` 下，将运维状态保存在 `~/.local/share/loopgate/state` 下，并将包装命令安装到 `~/.local/bin` 下。这种稳定的状态根目录是刻意为之的：审计历史和本地 策略状态在二进制文件升级后依然会保留。 如果您想固定特定的发布候选版本： ``` curl -fsSL https://raw.githubusercontent.com/aelithias/loopgate/main/scripts/install.sh | sh -s -- --version v0.2.0-rc2 ``` 打包发布和安装逻辑位于： - `scripts/package_release.sh` - `scripts/install.sh` 要求： - Go 1.26 或更高版本以从源码构建 - `PATH` 中存在 Python 3 以供 Claude hook 脚本使用 - Claude Code 用于基于 hook 的活动运行框架 从源码出发的最快路径： ``` make quickstart ``` `make quickstart` 会构建本地二进制文件并运行 `./bin/loopgate quickstart`， 这会应用推荐的默认设置： - 初始策略配置：`balanced` - 将 Claude Code hook 安装到 `~/.claude/` - 安装并加载 macOS LaunchAgent，使 Loopgate 在后台保持运行 然后验证本地的运维流程： ``` ./bin/loopgate status ./bin/loopgate test ``` 如果您想以交互方式选择选项，请使用引导式设置路径： ``` make build # 可选：将构建好的 binaries 安装到 ~/.local/bin make install-local ./bin/loopgate setup ``` 如果您运行过 `make install-local`，请将下方的 `./bin/...` 替换为裸命令 名，如 `loopgate` 和 `loopgate-policy-admin`。 `loopgate setup` 是引导式的首次运行路径。它会： - 初始化或复用您的本地策略签名密钥 - 让您选择初始策略配置：`balanced`、`strict` 或 `read-only` - 在修改本地状态之前显示设置计划 - 对所选策略进行签名 - 在安装 Claude hook 之前检查 `python3` - 安装 Claude Code hooks - 可以安装并加载 macOS LaunchAgent，使 Loopgate 在后台保持运行 - 最后会输出一份确定性的运维状态摘要，包含 `operator_mode`、所选配置、签名者的 `key_id`、策略路径、socket 路径、审计账本路径、派生出的 `readiness_state`、一个 `next_steps:` 区块以及下一步建议命令 初始配置： - `balanced` 是推荐的日常默认选项：Claude 的 `Read`、`Glob`、`Grep`、`Edit` 和 `MultiEdit` 在仓库根目录下保持开放，而 `Write` 和允许的 Bash 命令需要审批。 - `strict` 是针对更高敏感度环境的选项：读取仓库内文件保持开放，但所有 Claude 文件编辑都需要审批，且 Bash 保持禁用状态。 - `read-only` 是摩擦最低的评估配置：Claude 的 `Read`、`Glob` 和 `Grep` 在仓库根目录下保持开放，而 Claude 的写入和编辑、Bash 以及网络访问保持禁用。 如果您需要更宽泛的 `developer` 模板，请使用 `./bin/loopgate-policy-admin render-template -preset developer` 手动渲染并审查它。该模板作为一个实验性的备用出口保留， 并不属于受支持的 v1 设置路径的一部分。 重要提示： - Claude hook 的安装对于您 `~/.claude/` 下的本地 Claude Code 配置而言是全局性的 - 除非您移除这些 hooks，否则 Claude Code 将持续通过 Loopgate 路由受治理的 hook 事件 设置后的快速冒烟测试： 1. 运行 `./bin/loopgate status` 2. 运行 `./bin/loopgate test` 3. 如果您正在使用 Claude Code，请在 Claude Code 内运行 `/hooks` 并确认存在 7 个 Loopgate hook 条目 4. 让 Claude Code 读取 `README.md` 5. 运行 `./bin/loopgate-ledger tail -verbose` 预期结果： - `loopgate status` 应显示已签名的策略、签名者、`operator_mode`、`daemon_mode`、`launch_agent_state`、Claude hook 状态、socket 路径以及守护进程健康状态 - `loopgate test` 应打印出受治理的 `fs_list` 证明，以及对应的 `request_id`、审计账本路径、证据摘要，以及针对运行中与临时守护进程的正确后续步骤 - 您应该能看到针对您刚才触发的 Claude 操作产生的一条最近的 `hook.pre_validate` 审计事件 - 如果该请求需要审批或被拒绝，tail 的输出也会明确指出这一点 这个证明比启动文本更重要：只有当真实的 工具执行路径受到治理时，Loopgate 才是有用的，而不是仅仅在纸面上存在策略。 如果您偏好手动的运维操作路径，请参阅 [设置](./docs/setup/SETUP.md)。 首次启动时，Loopgate 可能会请求 macOS Keychain 创建默认的审计 HMAC 检查点密钥。如果 Keychain 访问被拒绝或取消，启动将进入失败关闭状态， 您应当从交互式的 macOS 登录会话中重新运行。 对于依赖 Keychain 的命令，请优先使用稳定的 `./bin/...` 二进制文件，而不是 `go run`。每次全新的 `go run` 构建都会更改可执行文件的身份，可能会 触发 macOS 的反复审批提示。 在终端中运行 `./bin/loopgate` 会使其附着在该终端上。 要在 macOS 上实现更持久的后台运行路径，请安装 LaunchAgent： ``` ./bin/loopgate install-launch-agent -load ``` 该 LaunchAgent 会固定当前的 Loopgate 可执行文件路径，因此请使用已构建的 `./bin/loopgate` 或已安装的 `loopgate` 二进制文件，而不是 `go run`。 如果您稍后想再次移除 Loopgate 的系统级配置： ``` ./bin/loopgate uninstall ./bin/loopgate uninstall --purge ``` `loopgate uninstall` 会移除由 Loopgate 管理的 Claude hook 条目，将 复制的 Loopgate hook 脚本从 `~/.claude/hooks/` 中删除，并在存在时 卸载/移除对应仓库的 macOS LaunchAgent。它刻意保留了本地的 二进制文件、已签名的策略文件以及运行时/审计状态，因此对证据或 运维数据的删除操作始终必须是显式的。该命令现在会为您指出 适合您当前模式的后续卸载步骤，包括 `loopgate uninstall --purge` 或 `./bin/loopgate uninstall --purge`，并会打印一份简明的 `offboarding_state` 摘要。 `loopgate uninstall --purge` 是更彻底的本地卸载路径。它还会 移除仓库作用域内的 `runtime/` 状态、`~/.local/bin` 下存在的默认安装的 Loopgate 二进制文件，以及与当前 策略 `key_id` 绑定的本地签名者材料。它依然不会删除受版本控制的仓库文件，例如 `core/policy/policy.yaml` 或 `core/policy/policy.yaml.sig`。对于源代码 检出环境，删除仓库本身仍需手动进行显式操作。对于发布的 安装版本，受管理的安装根目录会被移除，但如果外部签名者的 信任材料不是由该安装过程拥有的，它们可能仍然会被保留。 实用的底层移除命令： ``` ./bin/loopgate remove-hooks ./bin/loopgate remove-launch-agent make uninstall-local ``` 仅当您之前将二进制文件复制到了本地安装目录（如 `~/.local/bin`）时，才需使用 `make uninstall-local`。 如果您偏好直接从仓库根目录通过简单的 shell 管理后台运行： ``` mkdir -p runtime/logs runtime/state nohup ./bin/loopgate > runtime/logs/loopgate.stdout.log 2> runtime/logs/loopgate.stderr.log < /dev/null & echo $! > runtime/state/loopgate.pid ``` 停止该后台进程： ``` kill "$(cat runtime/state/loopgate.pid)" ``` 默认本地 socket： ``` runtime/state/loopgate.sock ``` Loopgate 使用已签名的策略： ``` ./bin/loopgate-policy-sign -verify-setup ./bin/loopgate-policy-admin validate ``` `-verify-setup` 默认会推断当前已签名策略的 `key_id`。仅当您 有意想要针对与仓库当前 `core/policy/policy.yaml.sig` 不同的签名者 进行验证或应用时，才传入 `-key-id`。 如果 Loopgate 已经在运行： ``` ./bin/loopgate-policy-admin apply -verify-setup ``` ## 运维流程 当前的实际运维流程为： 1. 在本地启动 Loopgate2. 将 Claude Code hooks 连接到本地 socket 3. 针对您真实的低风险与需要审批的操作，调整已签名的策略 4. 在遇到拒绝、批准或意外情况时检查本地审计 5. 无需重启 Loopgate 即可热加载策略变更 从这里开始： - [入门指南](./docs/setup/GETTING_STARTED.md) - [运维指南](./docs/setup/OPERATOR_GUIDE.md) - [设置](./docs/setup/SETUP.md) - [策略参考](./docs/setup/POLICY_REFERENCE.md) - [术语表](./docs/setup/GLOSSARY.md) - [诊断工具和账本工具](./docs/setup/DOCTOR_AND_LEDGER.md) - [本地客户端的 HTTP API](./docs/setup/LOOPGATE_HTTP_API_FOR_LOCAL_CLIENTS.md) - [策略签名](./docs/setup/POLICY_SIGNING.md) - [账本与审计完整性](./docs/setup/LEDGER_AND_AUDIT_INTEGRITY.md) - [威胁模型](./docs/loopgate-threat-model.md) - [管理控制台 TUI MVP](./docs/roadmap/admin_console_tui_mvp.md) - [发布候选检查清单](./docs/roadmap/release_candidate_checklist.md) - [更新日志](./CHANGELOG.md) - [支持](./SUPPORT.md) - [安全报告](./SECURITY.md) ## 已知局限性 Loopgate 已具备发布条件，但它仍是一个处于实验阶段的本地优先 Alpha 版本。 需要牢记的当前现状： - 以 macOS 优先、单节点运维流程是目前已交付的核心范围 - Claude Code hooks 和受治理的 MCP broker 路径是当前实际可用的挂载点 - 引导路径支持的初始策略配置被刻意收窄：`balanced`、`strict` 和 `read-only` - 提供商支持的 OAuth/PKCE 连接流程在代码树中仍作为实验性基础工作保留，但它们并不属于 v1 核心上手指南的一部分 - 本地审计完整性是强大的本地机器证据，而非远程公证；关于确切的哈希链和检查点限制，请参阅 [账本与审计完整性](./docs/setup/LEDGER_AND_AUDIT_INTEGRITY.md) - 内部包的清理工作正在进行中，因此贡献者的开发体验正在不断改善，但尚未达到完美无瑕的程度 当前的差距追踪位于此处： - [当前产品差距](./docs/roadmap/loopgate_v1_product_gaps.md) - [发布候选检查清单](./docs/roadmap/release_candidate_checklist.md) ## 仓库结构 ``` cmd/loopgate/ primary Loopgate server claude/hooks/scripts/ tracked Claude hook bundle source copied by install-hooks cmd/loopgate-policy-sign/ policy signing CLI cmd/loopgate-policy-admin/ policy validate/diff/explain/apply CLI cmd/loopgate-doctor/ operator diagnostics CLI internal/loopgate/ Loopgate control plane and governed runtime core/policy/ signed policy files config/ runtime configuration docs/ setup, operator docs, architecture, reports runtime/ local state and logs (fully gitignored) ``` ## 相关代码库 Loopgate 的记忆和连续性工作现在位于单独的同级 代码库 `continuity` 中，因此本仓库可以专注于： - 策略 - 审批 - 审计 - Claude hook 治理 - 沙箱调解 - 受治理的 MCP broker 流程 不再描述当前 Loopgate 产品形态的历史设计说明和较旧的 产品规划已被移至单独的 `ARCHIVED` 代码库。 ## 如何了解当前行为 实验性软件，正在积极加固中。 要了解当前行为，请优先参阅 [docs/](./docs) 中面向运维人员的文档、正在运行的代码，以及 [core/policy/](./core/policy) 下的已签名策略文件。 ## 许可证 Loopgate 采用 Apache License, Version 2.0 进行授权。详见 [LICENSE](./LICENSE) 和 [NOTICE](./NOTICE)。 ## 支持 有关设置问题、非敏感的 Bug 报告和运维工作流问题， 请参阅 [SUPPORT.md](./SUPPORT.md)。对于漏洞报告或信任边界相关的 问题，请使用 [SECURITY.md](./SECURITY.md) 中描述的私密报告渠道。

标签：AI安全, AI辅助开发, Chat Copilot, EVTX分析, 审计日志, 本地优先, 权限控制, 策略管理