guardrail-engine 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agentguard/__init__.py +16 -0
- agentguard/_shell.py +9 -0
- agentguard/cli.py +32 -0
- agentguard/mcp.py +25 -0
- guardrail_engine/__init__.py +20 -0
- guardrail_engine/_engine/AGENTS.md +168 -0
- guardrail_engine/_engine/LICENSE +21 -0
- guardrail_engine/_engine/README.md +638 -0
- guardrail_engine/_engine/VERSION +1 -0
- guardrail_engine/_engine/checks/agents_md_check.py +169 -0
- guardrail_engine/_engine/checks/encoding_ruleset.py +122 -0
- guardrail_engine/_engine/checks/eslint_check.py +30 -0
- guardrail_engine/_engine/checks/example_code_check.py +162 -0
- guardrail_engine/_engine/checks/example_ruleset.py +176 -0
- guardrail_engine/_engine/checks/external_adapter.py +358 -0
- guardrail_engine/_engine/checks/file_types.py +55 -0
- guardrail_engine/_engine/checks/harness_guard.py +342 -0
- guardrail_engine/_engine/checks/harness_self_check.py +306 -0
- guardrail_engine/_engine/checks/registry.py +58 -0
- guardrail_engine/_engine/checks/registry_loader.py +47 -0
- guardrail_engine/_engine/checks/rule_base.py +923 -0
- guardrail_engine/_engine/checks/semgrep_check.py +31 -0
- guardrail_engine/_engine/config/harness.local.example.toml +64 -0
- guardrail_engine/_engine/config/harness.toml +96 -0
- guardrail_engine/_engine/docs/THREAT-MODEL.en.md +241 -0
- guardrail_engine/_engine/docs/THREAT-MODEL.md +241 -0
- guardrail_engine/_engine/docs/adr/0001-packaging-principles.en.md +30 -0
- guardrail_engine/_engine/docs/adr/0001-packaging-principles.md +30 -0
- guardrail_engine/_engine/docs/packaging/COMPAT.en.md +64 -0
- guardrail_engine/_engine/docs/packaging/COMPAT.md +64 -0
- guardrail_engine/_engine/docs/packaging/INSTALL.en.md +377 -0
- guardrail_engine/_engine/docs/packaging/INSTALL.md +378 -0
- guardrail_engine/_engine/docs/packaging/OPENCLAW.en.md +66 -0
- guardrail_engine/_engine/docs/packaging/OPENCLAW.md +66 -0
- guardrail_engine/_engine/docs/packaging/RUNBOOK.en.md +242 -0
- guardrail_engine/_engine/docs/packaging/RUNBOOK.md +242 -0
- guardrail_engine/_engine/golden-patterns/endtoend/task-management.md +153 -0
- guardrail_engine/_engine/golden-patterns/index.md +95 -0
- guardrail_engine/_engine/golden-patterns/patterns/backend/controller-repository.md +164 -0
- guardrail_engine/_engine/golden-patterns/patterns/backend/validation-and-errors.md +113 -0
- guardrail_engine/_engine/golden-patterns/patterns/cross-cutting/config-and-env.md +98 -0
- guardrail_engine/_engine/golden-patterns/patterns/cross-cutting/logging.md +89 -0
- guardrail_engine/_engine/golden-patterns/patterns/web/form-dialog.md +153 -0
- guardrail_engine/_engine/golden-patterns/patterns/web/list-page.md +209 -0
- guardrail_engine/_engine/golden-patterns/patterns/web/request-layer.md +98 -0
- guardrail_engine/_engine/golden-patterns/reference/backend/ApiResult.cs +13 -0
- guardrail_engine/_engine/golden-patterns/reference/backend/AppDbContext.cs +10 -0
- guardrail_engine/_engine/golden-patterns/reference/backend/GlobalExceptionMiddleware.cs +58 -0
- guardrail_engine/_engine/golden-patterns/reference/backend/TaskConstants.cs +19 -0
- guardrail_engine/_engine/golden-patterns/reference/backend/TaskContracts.cs +45 -0
- guardrail_engine/_engine/golden-patterns/reference/backend/TaskController.cs +78 -0
- guardrail_engine/_engine/golden-patterns/reference/backend/TaskEntity.cs +14 -0
- guardrail_engine/_engine/golden-patterns/reference/backend/TaskRepository.cs +167 -0
- guardrail_engine/_engine/golden-patterns/reference/config/runtime-config.js +13 -0
- guardrail_engine/_engine/golden-patterns/reference/web/request.js +43 -0
- guardrail_engine/_engine/golden-patterns/reference/web/task-form.vue +94 -0
- guardrail_engine/_engine/golden-patterns/reference/web/task-list.vue +209 -0
- guardrail_engine/_engine/golden-patterns/templates/00_/350/214/203/345/274/217/345/210/266/351/200/240/346/250/241/346/235/277.md +92 -0
- guardrail_engine/_engine/harness/_batch.py +43 -0
- guardrail_engine/_engine/harness/_config.py +754 -0
- guardrail_engine/_engine/harness/_engine_meta.py +78 -0
- guardrail_engine/_engine/harness/_eol_policy.py +260 -0
- guardrail_engine/_engine/harness/_errors.py +18 -0
- guardrail_engine/_engine/harness/_init_marker.py +57 -0
- guardrail_engine/_engine/harness/_protected.py +55 -0
- guardrail_engine/_engine/harness/_validate.py +387 -0
- guardrail_engine/_engine/harness/_yaml_compat.py +146 -0
- guardrail_engine/_engine/harness/agents/auto-gate.py +253 -0
- guardrail_engine/_engine/harness/coverage.py +510 -0
- guardrail_engine/_engine/harness/hook_dirs.py +39 -0
- guardrail_engine/_engine/harness/hooks/post-edit.py +105 -0
- guardrail_engine/_engine/harness/hooks/pre-commit.py +291 -0
- guardrail_engine/_engine/harness/hooks/pre-edit.py +33 -0
- guardrail_engine/_engine/harness/hooks-dir/commit-msg +156 -0
- guardrail_engine/_engine/harness/hooks-dir/pre-commit +146 -0
- guardrail_engine/_engine/harness/protected-patterns.txt +36 -0
- guardrail_engine/_engine/harness/run_gate.py +981 -0
- guardrail_engine/_engine/integrations/README.en.md +35 -0
- guardrail_engine/_engine/integrations/README.md +35 -0
- guardrail_engine/_engine/integrations/agent-rule-snippet.md +32 -0
- guardrail_engine/_engine/integrations/claude-code/README.md +69 -0
- guardrail_engine/_engine/integrations/codebuddy/README.md +129 -0
- guardrail_engine/_engine/integrations/codex/README.md +109 -0
- guardrail_engine/_engine/integrations/guardrail-engine-skill/SKILL.md +134 -0
- guardrail_engine/_engine/integrations/hermes/README.md +36 -0
- guardrail_engine/_engine/integrations/hooks/agentguard-gate-shim.py +98 -0
- guardrail_engine/_engine/integrations/hooks/agentguard-gate.py +826 -0
- guardrail_engine/_engine/integrations/opencode/README.md +62 -0
- guardrail_engine/_engine/integrations/opencode/agentguard-gate.ts +318 -0
- guardrail_engine/_engine/integrations/plugins/README.md +42 -0
- guardrail_engine/_engine/integrations/plugins/agentguard-marketplace/.claude-plugin/marketplace.json +14 -0
- guardrail_engine/_engine/integrations/plugins/agentguard-marketplace/README.md +27 -0
- guardrail_engine/_engine/integrations/plugins/agentguard-plugin/.claude-plugin/plugin.json +8 -0
- guardrail_engine/_engine/integrations/plugins/agentguard-plugin/.mcp.json +13 -0
- guardrail_engine/_engine/integrations/plugins/agentguard-plugin/README.md +28 -0
- guardrail_engine/_engine/integrations/plugins/build_marketplace.py +93 -0
- guardrail_engine/_engine/integrations/plugins/build_plugin.py +164 -0
- guardrail_engine/_engine/integrations/plugins/verify_plugin.py +141 -0
- guardrail_engine/_engine/integrations/qoder-cn/README.md +281 -0
- guardrail_engine/_engine/integrations/qoder-cn/settings.example.json +33 -0
- guardrail_engine/_engine/integrations/trae-cn/README.md +265 -0
- guardrail_engine/_engine/integrations/trae-cn/hooks.example.json +22 -0
- guardrail_engine/_engine/integrations/zcode/README.md +201 -0
- guardrail_engine/_engine/integrations/zcode/opencode-go-proxy.py +132 -0
- guardrail_engine/_engine/integrations/zcode/zcode-go.sh +28 -0
- guardrail_engine/_engine/sandbox/acceptance_check.py +323 -0
- guardrail_engine/_engine/sandbox/agents_audit.py +515 -0
- guardrail_engine/_engine/sandbox/agents_scaffold.py +658 -0
- guardrail_engine/_engine/sandbox/audit_reconcile.py +421 -0
- guardrail_engine/_engine/sandbox/bootstrap.py +209 -0
- guardrail_engine/_engine/sandbox/bootstrap_agent_env.sh +424 -0
- guardrail_engine/_engine/sandbox/check_client_configs.py +423 -0
- guardrail_engine/_engine/sandbox/check_contracts.py +266 -0
- guardrail_engine/_engine/sandbox/check_mojibake.py +83 -0
- guardrail_engine/_engine/sandbox/demo_gate.py +98 -0
- guardrail_engine/_engine/sandbox/demo_gate.sh +152 -0
- guardrail_engine/_engine/sandbox/doctor.sh +374 -0
- guardrail_engine/_engine/sandbox/eol_text.py +207 -0
- guardrail_engine/_engine/sandbox/fix_paths.py +163 -0
- guardrail_engine/_engine/sandbox/global_agents.py +429 -0
- guardrail_engine/_engine/sandbox/inject_harness_pointer.py +209 -0
- guardrail_engine/_engine/sandbox/install_engine_hooks.sh +163 -0
- guardrail_engine/_engine/sandbox/install_hooks.sh +199 -0
- guardrail_engine/_engine/sandbox/install_shim.py +395 -0
- guardrail_engine/_engine/sandbox/list_entries.py +117 -0
- guardrail_engine/_engine/sandbox/mutation_smoke.py +1890 -0
- guardrail_engine/_engine/sandbox/pack_release.py +576 -0
- guardrail_engine/_engine/sandbox/render_harness_placeholders.py +260 -0
- guardrail_engine/_engine/sandbox/rollback_harness_placeholders.py +80 -0
- guardrail_engine/_engine/sandbox/run_acceptance_all.py +92 -0
- guardrail_engine/_engine/sandbox/run_tests.py +236 -0
- guardrail_engine/_engine/sandbox/setup_machine.sh +227 -0
- guardrail_engine/_engine/sandbox/sink_table.txt +52 -0
- guardrail_engine/_engine/sandbox/sweep_coverage.sh +72 -0
- guardrail_engine/_engine/sandbox/uninstall.py +536 -0
- guardrail_engine/_engine/sandbox/upgrade.py +1122 -0
- guardrail_engine/_engine/sandbox/verify_integrations.sh +364 -0
- guardrail_engine/_engine/sandbox/verify_judge.py +199 -0
- guardrail_engine/_engine/sandbox/verify_release.py +706 -0
- guardrail_engine/_engine/sandbox/where.sh +11 -0
- guardrail_engine/_shell.py +421 -0
- guardrail_engine/cli.py +1972 -0
- guardrail_engine/mcp.py +652 -0
- guardrail_engine-0.2.0.dist-info/METADATA +711 -0
- guardrail_engine-0.2.0.dist-info/RECORD +149 -0
- guardrail_engine-0.2.0.dist-info/WHEEL +5 -0
- guardrail_engine-0.2.0.dist-info/entry_points.txt +3 -0
- guardrail_engine-0.2.0.dist-info/licenses/LICENSE +21 -0
- guardrail_engine-0.2.0.dist-info/top_level.txt +2 -0
agentguard/__init__.py
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# -*- coding: utf-8 -*-
|
|
2
|
+
"""兼容壳(2026-10-25 改名 guardrail-engine):`import agentguard` 仍可用。
|
|
3
|
+
|
|
4
|
+
本包只在 v0.2 迁移期存在,v0.3 移除。新代码请 `import guardrail_engine`;
|
|
5
|
+
命令行请用 `guardrail-engine`(`agentguard` 作为别名保留到 v0.3)。
|
|
6
|
+
"""
|
|
7
|
+
import warnings
|
|
8
|
+
|
|
9
|
+
warnings.warn(
|
|
10
|
+
"包名 agentguard 已改为 guardrail_engine(v0.3 移除兼容层);命令行推荐 guardrail-engine。",
|
|
11
|
+
DeprecationWarning, stacklevel=2)
|
|
12
|
+
|
|
13
|
+
from guardrail_engine import __version__, _version # noqa: E402,F401
|
|
14
|
+
from guardrail_engine import _shell as _shell # noqa: E402,F401
|
|
15
|
+
|
|
16
|
+
__all__ = ["__version__", "_version", "_shell"]
|
agentguard/_shell.py
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# -*- coding: utf-8 -*-
|
|
2
|
+
"""兼容壳:`agentguard._shell` → `guardrail_engine._shell`(v0.3 移除)。"""
|
|
3
|
+
import os
|
|
4
|
+
import sys
|
|
5
|
+
|
|
6
|
+
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
|
7
|
+
|
|
8
|
+
from guardrail_engine._shell import * # noqa: E402,F401,F403
|
|
9
|
+
from guardrail_engine._shell import __all__ # noqa: E402,F401
|
agentguard/cli.py
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
# -*- coding: utf-8 -*-
|
|
3
|
+
"""兼容壳:`agentguard` 命令行 → `guardrail_engine.cli`(v0.3 移除)。
|
|
4
|
+
|
|
5
|
+
脚本形态(`python agentguard/cli.py ...`)与安装形态(console script `agentguard`)
|
|
6
|
+
都走这里;统一打印一次弃用提示,然后原样转发。
|
|
7
|
+
"""
|
|
8
|
+
import os
|
|
9
|
+
import sys
|
|
10
|
+
|
|
11
|
+
for _stream in (sys.stdout, sys.stderr):
|
|
12
|
+
try:
|
|
13
|
+
_stream.reconfigure(encoding="utf-8", errors="replace")
|
|
14
|
+
except Exception:
|
|
15
|
+
pass
|
|
16
|
+
|
|
17
|
+
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
|
18
|
+
|
|
19
|
+
from guardrail_engine.cli import _require_python # noqa: E402
|
|
20
|
+
|
|
21
|
+
_DEPRECATION = ("[deprecated] 命令 agentguard 已改为 guardrail-engine(v0.3 移除别名)。\n")
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def main(argv=None):
|
|
25
|
+
sys.stderr.write(_DEPRECATION)
|
|
26
|
+
from guardrail_engine.cli import main as _main
|
|
27
|
+
return _main(argv)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
if __name__ == "__main__":
|
|
31
|
+
_require_python()
|
|
32
|
+
sys.exit(main())
|
agentguard/mcp.py
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# -*- coding: utf-8 -*-
|
|
2
|
+
"""兼容壳:`agentguard/mcp.py` → `guardrail_engine/mcp.py`(v0.3 移除)。
|
|
3
|
+
|
|
4
|
+
已有 MCP 配置里的 `<engine>/agentguard/mcp.py` 在迁移期继续可用。
|
|
5
|
+
"""
|
|
6
|
+
import os
|
|
7
|
+
import sys
|
|
8
|
+
|
|
9
|
+
for _stream in (sys.stdout, sys.stderr):
|
|
10
|
+
try:
|
|
11
|
+
_stream.reconfigure(encoding="utf-8", errors="replace")
|
|
12
|
+
except Exception:
|
|
13
|
+
pass
|
|
14
|
+
|
|
15
|
+
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
|
16
|
+
|
|
17
|
+
from guardrail_engine.mcp import * # noqa: E402,F401,F403
|
|
18
|
+
from guardrail_engine.mcp import _require_python, main # noqa: E402
|
|
19
|
+
|
|
20
|
+
sys.stderr.write(
|
|
21
|
+
"[deprecated] MCP 入口 agentguard/mcp.py 已改为 guardrail_engine/mcp.py"
|
|
22
|
+
"(v0.3 移除兼容路径)。\n")
|
|
23
|
+
|
|
24
|
+
if __name__ == "__main__":
|
|
25
|
+
sys.exit(main())
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# -*- coding: utf-8 -*-
|
|
2
|
+
"""guardrail_engine:guardrail-engine 的薄壳集合(ADR-0001:壳只转发,逻辑只一份)。
|
|
3
|
+
|
|
4
|
+
- cli.py : 统一命令行入口(运行 / 台账 / 安装 / 旁路 / 回滚)
|
|
5
|
+
- mcp.py : 单文件零依赖 MCP 薄服务(stdio JSON-RPC)
|
|
6
|
+
- _shell.py: 三个入口共用的环境定位件(工程根 / 版本 / 解释器 / 前置检查 / gate 归属匹配)
|
|
7
|
+
|
|
8
|
+
版本单一来源(ADR-0001 铁律 3):本文件的 `__version__`、`cli._version()`、`mcp.VERSION`
|
|
9
|
+
都走 `_shell.read_version()` 的**同一份**实现。此前三处各写一遍且回退链不同 ——
|
|
10
|
+
轮子安装形态(包内不带 VERSION 文件)下同一个包会报出两个版本号(剖析报告 N1)。
|
|
11
|
+
"""
|
|
12
|
+
from . import _shell
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def _version():
|
|
16
|
+
"""本包版本 —— 转发公用件(保留本名以维持既有调用面)。"""
|
|
17
|
+
return _shell.read_version()
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
__version__ = _version()
|
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
# Guardrail Engine(原 AgentGuard)—— 统一门禁工程地图(所有 AI agent 通用)
|
|
2
|
+
|
|
3
|
+
> 本文件是给任何 AI agent 读的「这是哪里、有哪些规则、怎么触发」。Claude Code /
|
|
4
|
+
> Codex / OpenCode / CodeBuddy / Hermes 只要能执行 shell 命令即可遵守本工程。
|
|
5
|
+
> 核心原则:**人类掌舵,Agent 执行。门禁是代码库的硬边界,不是建议。**
|
|
6
|
+
|
|
7
|
+
## 这个工程是什么
|
|
8
|
+
|
|
9
|
+
Guardrail Engine 是一个**通用代码门禁框架**,用于在编辑期和提交期自动检查代码是否符合团队约定。
|
|
10
|
+
各仓库通过固定路径引用本工程。约束规则全部集中在 `checks/`,策略集中在配置,
|
|
11
|
+
**规则是单一事实源,不要在业务代码仓库里各写一套。**
|
|
12
|
+
|
|
13
|
+
## 仓库结构速览
|
|
14
|
+
|
|
15
|
+
- `config/harness.toml` —— gate 清单与策略:enabled / strict|loose / run_on / 行尾。
|
|
16
|
+
`[repos]` 段**只声明键名、值一律留空**(受管仓库名单是团队策略,与机器无关;键名不许动)。
|
|
17
|
+
- `config/harness.local.toml` —— **本机事实**:各仓库在自己磁盘上的路径(git 忽略)。
|
|
18
|
+
键值留空 = 这台机器没配该仓,逐条 `⊘` 提示但不阻断;键名不在共享配置里才是真配置错。
|
|
19
|
+
改策略不碰脚本。
|
|
20
|
+
- `checks/*.py` —— 各端门禁脚本与规则集。
|
|
21
|
+
- `golden-patterns/index.md` —— 黄金范式索引:按任务组织的**代码骨架库**(请求层 / 列表页 /
|
|
22
|
+
表单弹窗 / 后端分层 / 校验 / 日志 / 配置 + 业务端到端范本)。规则命中时输出
|
|
23
|
+
`📖 See: <仓库相对路径>`,顺着它读;`reference/` 是完整参考实现,`templates/` 教怎么造新范式。
|
|
24
|
+
- `harness/run_gate.py` —— 统一调度器(按 gate 名调 checks)。
|
|
25
|
+
- `harness/coverage.py` —— 覆盖度自评(`run_gate.py --coverage`):哪些规则真触发过、哪些一次没响。
|
|
26
|
+
- `harness/agents/auto-gate.py` —— AI agent 通用入口(在仓库目录下跑,自动识别 gate)。
|
|
27
|
+
- `harness/hooks/*` —— git hook 触发点(pre-edit / post-edit / pre-commit)。
|
|
28
|
+
- `sandbox/install_hooks.sh` —— 给端仓库装 git pre-commit(agent 无关的强制层)。
|
|
29
|
+
|
|
30
|
+
## Agent 必须遵守的规则
|
|
31
|
+
|
|
32
|
+
1. **改码前**(pre-edit):确保改动清单 / 方案已和用户确认,不要自己设计大改动突袭。
|
|
33
|
+
2. **改码后进门禁**:在改动仓库的根目录下,或带上 `--repo`,跑通用门禁——
|
|
34
|
+
```
|
|
35
|
+
python <HARNESS>/harness/agents/auto-gate.py
|
|
36
|
+
```
|
|
37
|
+
或指定 repo:
|
|
38
|
+
```
|
|
39
|
+
python <HARNESS>/harness/run_gate.py <gate名> <文件...>
|
|
40
|
+
```
|
|
41
|
+
退出码:`0` 通过 / `1` 拦截 / `2` 配置错 / `3` 非受管仓。
|
|
42
|
+
3. **不加规则外的例外**:`harness-ok:` 注释只用于**文件级规则不适用**的场景,
|
|
43
|
+
且必须写明理由。规则 ID 必须写对、理由必填。
|
|
44
|
+
4. **不改引擎层除非被要求**:`checks/` + `harness/` + `guardrail_engine/`(含兼容壳 `agentguard/`)
|
|
45
|
+
受保护,改动需在提交消息带 `[harness]` 标记。
|
|
46
|
+
5. **零第三方依赖**:引擎层只用 Python 标准库,新增依赖需明确批准。外部 ESLint / Semgrep
|
|
47
|
+
适配 gate 是**可选的外部进程**(默认关闭),不计入引擎依赖;工具没装时开启该 gate 会
|
|
48
|
+
fail-closed 到 rc=2。
|
|
49
|
+
|
|
50
|
+
## 行内豁免(合规写法被误报时的唯一出路)
|
|
51
|
+
|
|
52
|
+
有些规则机械判不出来。这时**不要改规则、不要删代码绕过**,在命中行的
|
|
53
|
+
**本行或紧邻上一行**加标记:
|
|
54
|
+
|
|
55
|
+
```js
|
|
56
|
+
// harness-ok: NO-CONSOLE 调试日志已用条件封装
|
|
57
|
+
if (DEBUG) console.log("debug info")
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
- 标记必须落在**注释**里 —— 字符串字面量里的不算。
|
|
61
|
+
- 规则 ID 必须写对,**并且跟一句非空理由**。
|
|
62
|
+
- 先看清这条规则**是否适用**。被一条明显不适用的规则拦住 → 改配置或报给维护者。
|
|
63
|
+
|
|
64
|
+
## 黄金范式(写码前的正向指引)
|
|
65
|
+
|
|
66
|
+
门禁回答「不能这么写」,`golden-patterns/` 回答「照这个写」。它不是规则清单,而是按
|
|
67
|
+
「你要写什么」组织的已验收骨架:请求层、列表页、表单弹窗、后端分层、校验与错误、日志、配置,
|
|
68
|
+
外加一个从常量到页面的业务全链范本。规则类声明 `see` 后,命中输出会多一行
|
|
69
|
+
`📖 See: <仓库相对路径>` —— 被拦的那一刻先读它,再改代码。
|
|
70
|
+
|
|
71
|
+
入口是 `golden-patterns/index.md`;`reference/` 下的正面样板必须自己也能过门禁(测试会跑)。
|
|
72
|
+
团队新范式放进 `golden-patterns/patterns/<端或主题>/` 或 `golden-patterns/endtoend/`,
|
|
73
|
+
先读 `golden-patterns/templates/00_范式制造模板.md`,并在规则上写 `see` 对接。
|
|
74
|
+
|
|
75
|
+
## Git 强制层(无需 agent 配合,自动生效)
|
|
76
|
+
|
|
77
|
+
- 端仓库 `pre-commit`:commit 先跑对应门禁,未通过阻断。
|
|
78
|
+
- 端仓库 `harness_guard`:防 AI 为过门禁而暗改受保护文件。
|
|
79
|
+
- 本工程自身两层钩子:checks 语法门禁 + commit-msg 需 `[harness]` 标记(防改坏门禁脚本)。
|
|
80
|
+
|
|
81
|
+
## 保护循环(防 AI 改门禁敷衍了事)
|
|
82
|
+
|
|
83
|
+
- 改 `checks/*.py` 或 `config/harness.toml` 属于 harness 维护,需 commit 消息带 `[harness]`。
|
|
84
|
+
- 带 `[harness]` 的提交还要在消息末尾加一行 `Engine-Sha: <16 位哈希>`,值取自
|
|
85
|
+
`python harness/run_gate.py --engine-sha`;CI 会按该提交内容重算并比对(不一致即失败)。
|
|
86
|
+
台账里的 `engine_sha` 靠这组尾注归因(`guardrail_engine/cli.py log --verify --engine`)。
|
|
87
|
+
- 规则对齐真实架构,别照搬教条。
|
|
88
|
+
|
|
89
|
+
## 快速命令
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
# 列出所有 gate
|
|
93
|
+
python harness/run_gate.py --list
|
|
94
|
+
|
|
95
|
+
# 自动识别并检查改动
|
|
96
|
+
python harness/agents/auto-gate.py
|
|
97
|
+
|
|
98
|
+
# 指定 gate 定向检查
|
|
99
|
+
python harness/run_gate.py <gate> <文件...>
|
|
100
|
+
|
|
101
|
+
# 指定 gate 全量扫描
|
|
102
|
+
python harness/run_gate.py <gate> --all
|
|
103
|
+
|
|
104
|
+
# 配置体检(全舰队 AGENTS.md 检查也在这里;提交期只查本次目标仓)
|
|
105
|
+
python harness/run_gate.py --validate
|
|
106
|
+
|
|
107
|
+
# 门禁子进程时限(秒,默认 1800;超时杀整棵进程树、按 rc=2 处理,台账记 timed_out)
|
|
108
|
+
export GUARDRAIL_GATE_TIMEOUT=1800
|
|
109
|
+
|
|
110
|
+
# 运行摘要
|
|
111
|
+
python harness/run_gate.py --summary
|
|
112
|
+
|
|
113
|
+
# 覆盖度报告
|
|
114
|
+
python harness/run_gate.py --coverage
|
|
115
|
+
|
|
116
|
+
# 安装提交 hook
|
|
117
|
+
sh sandbox/install_hooks.sh <gate>
|
|
118
|
+
|
|
119
|
+
# 安装编辑期转发器
|
|
120
|
+
python sandbox/install_shim.py
|
|
121
|
+
|
|
122
|
+
# 接入自检
|
|
123
|
+
sh sandbox/doctor.sh
|
|
124
|
+
|
|
125
|
+
# 快速测试
|
|
126
|
+
python sandbox/run_tests.py --fast
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## 规则模型
|
|
130
|
+
|
|
131
|
+
所有规则继承 `checks/rule_base.py` 的 `Rule` 基类。
|
|
132
|
+
|
|
133
|
+
### 示例规则
|
|
134
|
+
|
|
135
|
+
项目自带 3 条示例规则(`checks/example_ruleset.py`):
|
|
136
|
+
|
|
137
|
+
| 规则 ID | 检查内容 | 严重级别 |
|
|
138
|
+
|---|---|---|
|
|
139
|
+
| `NO-CONSOLE` | 禁止 `console.log` 残留 | block |
|
|
140
|
+
| `NO-HARDIP` | 禁止硬编码 IP 地址 | block |
|
|
141
|
+
| `EOL-UNIFIED` | 行尾不统一(CRLF / LF 混用) | block |
|
|
142
|
+
|
|
143
|
+
运行示例规则:
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
python checks/example_code_check.py --repo <仓库路径> --all
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
## 路径约定
|
|
150
|
+
|
|
151
|
+
`<HARNESS>` 指本工程根目录。求值方式(统一解析链,优先级从高到低):
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
# ① 环境变量
|
|
155
|
+
echo "$GUARDRAIL_ENGINE_DIR"
|
|
156
|
+
|
|
157
|
+
# ② 本机配置文件(config/harness.local.toml → harness 键)
|
|
158
|
+
# ③ 从模块所在目录(__file__)向上找(源码树 / 安装副本自定位)
|
|
159
|
+
# ④ 指针文件(~/.guardrail-engine/harness.path)—— 仅 pip/wheel 形态需要
|
|
160
|
+
|
|
161
|
+
# 不确定工程根时跑
|
|
162
|
+
python guardrail_engine/cli.py where
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
## 给 Agent 的提醒
|
|
166
|
+
|
|
167
|
+
- 看不懂规则先读配置文件,不要凭感觉猜;有歧义问用户,别自行假设业务逻辑。
|
|
168
|
+
- 详细文档见 `README.md` 和 `docs/` 目录。
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 AgentGuard
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|