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.
Files changed (149) hide show
  1. agentguard/__init__.py +16 -0
  2. agentguard/_shell.py +9 -0
  3. agentguard/cli.py +32 -0
  4. agentguard/mcp.py +25 -0
  5. guardrail_engine/__init__.py +20 -0
  6. guardrail_engine/_engine/AGENTS.md +168 -0
  7. guardrail_engine/_engine/LICENSE +21 -0
  8. guardrail_engine/_engine/README.md +638 -0
  9. guardrail_engine/_engine/VERSION +1 -0
  10. guardrail_engine/_engine/checks/agents_md_check.py +169 -0
  11. guardrail_engine/_engine/checks/encoding_ruleset.py +122 -0
  12. guardrail_engine/_engine/checks/eslint_check.py +30 -0
  13. guardrail_engine/_engine/checks/example_code_check.py +162 -0
  14. guardrail_engine/_engine/checks/example_ruleset.py +176 -0
  15. guardrail_engine/_engine/checks/external_adapter.py +358 -0
  16. guardrail_engine/_engine/checks/file_types.py +55 -0
  17. guardrail_engine/_engine/checks/harness_guard.py +342 -0
  18. guardrail_engine/_engine/checks/harness_self_check.py +306 -0
  19. guardrail_engine/_engine/checks/registry.py +58 -0
  20. guardrail_engine/_engine/checks/registry_loader.py +47 -0
  21. guardrail_engine/_engine/checks/rule_base.py +923 -0
  22. guardrail_engine/_engine/checks/semgrep_check.py +31 -0
  23. guardrail_engine/_engine/config/harness.local.example.toml +64 -0
  24. guardrail_engine/_engine/config/harness.toml +96 -0
  25. guardrail_engine/_engine/docs/THREAT-MODEL.en.md +241 -0
  26. guardrail_engine/_engine/docs/THREAT-MODEL.md +241 -0
  27. guardrail_engine/_engine/docs/adr/0001-packaging-principles.en.md +30 -0
  28. guardrail_engine/_engine/docs/adr/0001-packaging-principles.md +30 -0
  29. guardrail_engine/_engine/docs/packaging/COMPAT.en.md +64 -0
  30. guardrail_engine/_engine/docs/packaging/COMPAT.md +64 -0
  31. guardrail_engine/_engine/docs/packaging/INSTALL.en.md +377 -0
  32. guardrail_engine/_engine/docs/packaging/INSTALL.md +378 -0
  33. guardrail_engine/_engine/docs/packaging/OPENCLAW.en.md +66 -0
  34. guardrail_engine/_engine/docs/packaging/OPENCLAW.md +66 -0
  35. guardrail_engine/_engine/docs/packaging/RUNBOOK.en.md +242 -0
  36. guardrail_engine/_engine/docs/packaging/RUNBOOK.md +242 -0
  37. guardrail_engine/_engine/golden-patterns/endtoend/task-management.md +153 -0
  38. guardrail_engine/_engine/golden-patterns/index.md +95 -0
  39. guardrail_engine/_engine/golden-patterns/patterns/backend/controller-repository.md +164 -0
  40. guardrail_engine/_engine/golden-patterns/patterns/backend/validation-and-errors.md +113 -0
  41. guardrail_engine/_engine/golden-patterns/patterns/cross-cutting/config-and-env.md +98 -0
  42. guardrail_engine/_engine/golden-patterns/patterns/cross-cutting/logging.md +89 -0
  43. guardrail_engine/_engine/golden-patterns/patterns/web/form-dialog.md +153 -0
  44. guardrail_engine/_engine/golden-patterns/patterns/web/list-page.md +209 -0
  45. guardrail_engine/_engine/golden-patterns/patterns/web/request-layer.md +98 -0
  46. guardrail_engine/_engine/golden-patterns/reference/backend/ApiResult.cs +13 -0
  47. guardrail_engine/_engine/golden-patterns/reference/backend/AppDbContext.cs +10 -0
  48. guardrail_engine/_engine/golden-patterns/reference/backend/GlobalExceptionMiddleware.cs +58 -0
  49. guardrail_engine/_engine/golden-patterns/reference/backend/TaskConstants.cs +19 -0
  50. guardrail_engine/_engine/golden-patterns/reference/backend/TaskContracts.cs +45 -0
  51. guardrail_engine/_engine/golden-patterns/reference/backend/TaskController.cs +78 -0
  52. guardrail_engine/_engine/golden-patterns/reference/backend/TaskEntity.cs +14 -0
  53. guardrail_engine/_engine/golden-patterns/reference/backend/TaskRepository.cs +167 -0
  54. guardrail_engine/_engine/golden-patterns/reference/config/runtime-config.js +13 -0
  55. guardrail_engine/_engine/golden-patterns/reference/web/request.js +43 -0
  56. guardrail_engine/_engine/golden-patterns/reference/web/task-form.vue +94 -0
  57. guardrail_engine/_engine/golden-patterns/reference/web/task-list.vue +209 -0
  58. 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
  59. guardrail_engine/_engine/harness/_batch.py +43 -0
  60. guardrail_engine/_engine/harness/_config.py +754 -0
  61. guardrail_engine/_engine/harness/_engine_meta.py +78 -0
  62. guardrail_engine/_engine/harness/_eol_policy.py +260 -0
  63. guardrail_engine/_engine/harness/_errors.py +18 -0
  64. guardrail_engine/_engine/harness/_init_marker.py +57 -0
  65. guardrail_engine/_engine/harness/_protected.py +55 -0
  66. guardrail_engine/_engine/harness/_validate.py +387 -0
  67. guardrail_engine/_engine/harness/_yaml_compat.py +146 -0
  68. guardrail_engine/_engine/harness/agents/auto-gate.py +253 -0
  69. guardrail_engine/_engine/harness/coverage.py +510 -0
  70. guardrail_engine/_engine/harness/hook_dirs.py +39 -0
  71. guardrail_engine/_engine/harness/hooks/post-edit.py +105 -0
  72. guardrail_engine/_engine/harness/hooks/pre-commit.py +291 -0
  73. guardrail_engine/_engine/harness/hooks/pre-edit.py +33 -0
  74. guardrail_engine/_engine/harness/hooks-dir/commit-msg +156 -0
  75. guardrail_engine/_engine/harness/hooks-dir/pre-commit +146 -0
  76. guardrail_engine/_engine/harness/protected-patterns.txt +36 -0
  77. guardrail_engine/_engine/harness/run_gate.py +981 -0
  78. guardrail_engine/_engine/integrations/README.en.md +35 -0
  79. guardrail_engine/_engine/integrations/README.md +35 -0
  80. guardrail_engine/_engine/integrations/agent-rule-snippet.md +32 -0
  81. guardrail_engine/_engine/integrations/claude-code/README.md +69 -0
  82. guardrail_engine/_engine/integrations/codebuddy/README.md +129 -0
  83. guardrail_engine/_engine/integrations/codex/README.md +109 -0
  84. guardrail_engine/_engine/integrations/guardrail-engine-skill/SKILL.md +134 -0
  85. guardrail_engine/_engine/integrations/hermes/README.md +36 -0
  86. guardrail_engine/_engine/integrations/hooks/agentguard-gate-shim.py +98 -0
  87. guardrail_engine/_engine/integrations/hooks/agentguard-gate.py +826 -0
  88. guardrail_engine/_engine/integrations/opencode/README.md +62 -0
  89. guardrail_engine/_engine/integrations/opencode/agentguard-gate.ts +318 -0
  90. guardrail_engine/_engine/integrations/plugins/README.md +42 -0
  91. guardrail_engine/_engine/integrations/plugins/agentguard-marketplace/.claude-plugin/marketplace.json +14 -0
  92. guardrail_engine/_engine/integrations/plugins/agentguard-marketplace/README.md +27 -0
  93. guardrail_engine/_engine/integrations/plugins/agentguard-plugin/.claude-plugin/plugin.json +8 -0
  94. guardrail_engine/_engine/integrations/plugins/agentguard-plugin/.mcp.json +13 -0
  95. guardrail_engine/_engine/integrations/plugins/agentguard-plugin/README.md +28 -0
  96. guardrail_engine/_engine/integrations/plugins/build_marketplace.py +93 -0
  97. guardrail_engine/_engine/integrations/plugins/build_plugin.py +164 -0
  98. guardrail_engine/_engine/integrations/plugins/verify_plugin.py +141 -0
  99. guardrail_engine/_engine/integrations/qoder-cn/README.md +281 -0
  100. guardrail_engine/_engine/integrations/qoder-cn/settings.example.json +33 -0
  101. guardrail_engine/_engine/integrations/trae-cn/README.md +265 -0
  102. guardrail_engine/_engine/integrations/trae-cn/hooks.example.json +22 -0
  103. guardrail_engine/_engine/integrations/zcode/README.md +201 -0
  104. guardrail_engine/_engine/integrations/zcode/opencode-go-proxy.py +132 -0
  105. guardrail_engine/_engine/integrations/zcode/zcode-go.sh +28 -0
  106. guardrail_engine/_engine/sandbox/acceptance_check.py +323 -0
  107. guardrail_engine/_engine/sandbox/agents_audit.py +515 -0
  108. guardrail_engine/_engine/sandbox/agents_scaffold.py +658 -0
  109. guardrail_engine/_engine/sandbox/audit_reconcile.py +421 -0
  110. guardrail_engine/_engine/sandbox/bootstrap.py +209 -0
  111. guardrail_engine/_engine/sandbox/bootstrap_agent_env.sh +424 -0
  112. guardrail_engine/_engine/sandbox/check_client_configs.py +423 -0
  113. guardrail_engine/_engine/sandbox/check_contracts.py +266 -0
  114. guardrail_engine/_engine/sandbox/check_mojibake.py +83 -0
  115. guardrail_engine/_engine/sandbox/demo_gate.py +98 -0
  116. guardrail_engine/_engine/sandbox/demo_gate.sh +152 -0
  117. guardrail_engine/_engine/sandbox/doctor.sh +374 -0
  118. guardrail_engine/_engine/sandbox/eol_text.py +207 -0
  119. guardrail_engine/_engine/sandbox/fix_paths.py +163 -0
  120. guardrail_engine/_engine/sandbox/global_agents.py +429 -0
  121. guardrail_engine/_engine/sandbox/inject_harness_pointer.py +209 -0
  122. guardrail_engine/_engine/sandbox/install_engine_hooks.sh +163 -0
  123. guardrail_engine/_engine/sandbox/install_hooks.sh +199 -0
  124. guardrail_engine/_engine/sandbox/install_shim.py +395 -0
  125. guardrail_engine/_engine/sandbox/list_entries.py +117 -0
  126. guardrail_engine/_engine/sandbox/mutation_smoke.py +1890 -0
  127. guardrail_engine/_engine/sandbox/pack_release.py +576 -0
  128. guardrail_engine/_engine/sandbox/render_harness_placeholders.py +260 -0
  129. guardrail_engine/_engine/sandbox/rollback_harness_placeholders.py +80 -0
  130. guardrail_engine/_engine/sandbox/run_acceptance_all.py +92 -0
  131. guardrail_engine/_engine/sandbox/run_tests.py +236 -0
  132. guardrail_engine/_engine/sandbox/setup_machine.sh +227 -0
  133. guardrail_engine/_engine/sandbox/sink_table.txt +52 -0
  134. guardrail_engine/_engine/sandbox/sweep_coverage.sh +72 -0
  135. guardrail_engine/_engine/sandbox/uninstall.py +536 -0
  136. guardrail_engine/_engine/sandbox/upgrade.py +1122 -0
  137. guardrail_engine/_engine/sandbox/verify_integrations.sh +364 -0
  138. guardrail_engine/_engine/sandbox/verify_judge.py +199 -0
  139. guardrail_engine/_engine/sandbox/verify_release.py +706 -0
  140. guardrail_engine/_engine/sandbox/where.sh +11 -0
  141. guardrail_engine/_shell.py +421 -0
  142. guardrail_engine/cli.py +1972 -0
  143. guardrail_engine/mcp.py +652 -0
  144. guardrail_engine-0.2.0.dist-info/METADATA +711 -0
  145. guardrail_engine-0.2.0.dist-info/RECORD +149 -0
  146. guardrail_engine-0.2.0.dist-info/WHEEL +5 -0
  147. guardrail_engine-0.2.0.dist-info/entry_points.txt +3 -0
  148. guardrail_engine-0.2.0.dist-info/licenses/LICENSE +21 -0
  149. guardrail_engine-0.2.0.dist-info/top_level.txt +2 -0
@@ -0,0 +1,638 @@
1
+ # Guardrail Engine
2
+
3
+ [![CI](https://github.com/rain610/guardrail-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/rain610/guardrail-engine/actions/workflows/ci.yml)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
+ [![Python: 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
6
+ [![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)](https://github.com/rain610/guardrail-engine)
7
+
8
+ > 零依赖、可扩展的代码门禁引擎 —— 把"规范"从"靠人记"变成"靠机器判"。
9
+
10
+ [English](README.en.md) | 简体中文
11
+
12
+ > 本项目原名 **AgentGuard**,v0.2 起更名为 **Guardrail Engine**。旧命令 `agentguard`、
13
+ > 旧导入包与旧配置目录在迁移期内继续可用(见 [CHANGELOG](CHANGELOG.md))。Claude 插件 ID
14
+ > `agentguard@agentguard-tools` 与 hook 文件名 `agentguard-gate.py` 暂不改:已安装用户无需重装,
15
+ > v0.3 与兼容壳一起迁移。
16
+
17
+ Guardrail Engine 是一个**通用代码门禁框架**,用于在编辑期和提交期自动检查代码是否符合团队约定。
18
+
19
+ 它不是 lint 工具(ESLint / SonarQube 那类代码分析器),而是**策略强制平面**(policy enforcement plane)—— 决定"这次提交过不过"。对标物是 Claude Code 的 hooks / permissions、Codex 的 execpolicy。
20
+
21
+ 它也不替代 `AGENTS.md`:`AGENTS.md` 管架构意图、业务语义(需要人/模型判断),Guardrail Engine 管**能被机械判定**的事。两者是分工。
22
+
23
+ ## 核心价值
24
+
25
+ | 痛点 | Guardrail Engine 怎么解 |
26
+ |---|---|
27
+ | 规范写在文档里,AI / 开发者记不住 | 常驻只注入约 2.4KB 的全局守则(`~/.guardrail-engine/GLOBAL_AGENTS.md`,不是仓库根的 `AGENTS.md`),细节按需加载 |
28
+ | 约定只对"愿意遵守的人"有效 | 编辑期 + 提交期双重拦截,忘了也会被拦 |
29
+ | 一上规则就被存量旧账淹没 | 双态 severity:新代码 `error` 拦截,存量 `info` 观察 |
30
+ | "门禁跑没跑"说不清 | 每次判定写台账,可查看运行摘要与规则覆盖度 |
31
+ | 引入工具链的依赖成本 | **零第三方依赖**,只用 Python 标准库 |
32
+
33
+ 引擎层**不依赖任何个人** skill / 工具:同事 clone 或 `pip install` 完即可运行。
34
+
35
+ ## 开箱即用的内容(诚实说明)
36
+
37
+ Guardrail Engine 是一个**框架**,不是即装即用的规则集。你需要自己写规则,或者从社区获取。
38
+
39
+ **内置的内容:**
40
+
41
+ - 3 条**示例规则**(`checks/example_ruleset.py`):`NO-CONSOLE`、`NO-HARDIP`、`EOL-UNIFIED` —— 展示如何写规则,不是生产级规则集。
42
+ - **黄金范式库**(`golden-patterns/`):请求层、列表页、表单弹窗、后端分层等骨架 —— 这是**团队示例**,展示"照这个写",不是通用规范。
43
+ - **引擎基础设施**:调度层、台账、覆盖度自评、变异冒烟、tamper-evident 审计链 —— 这是核心价值,让你能写自己的规则并证明它们有牙齿。
44
+
45
+ **不包含的内容:**
46
+
47
+ - 行业通用规则集(如"禁止硬编码密钥"、"必须写单元测试")—— 这些需要团队自己定义。
48
+ - 业务特定规则 —— 你的项目约定只有你知道。
49
+ - 第三方 linter 集成(ESLint、SonarQube)—— 可选适配器存在,但默认关闭,且引入外部依赖。
50
+
51
+ **适合的用户:**
52
+
53
+ - 有明确团队规范,需要机械化强制执行。
54
+ - 愿意花时间写自己的规则(参考示例规则和黄金范式)。
55
+ - 需要审计链和覆盖度报告来证明"门禁真的在跑"。
56
+
57
+ **不适合的用户:**
58
+
59
+ - 期望装完就有 50 条规则直接用的(考虑 gitleaks、pre-commit 生态)。
60
+ - 不想写规则,只想跑 lint 的(考虑 ESLint、SonarQube)。
61
+
62
+ ## 前置条件
63
+
64
+ | 依赖 | 最低版本 | 用途 |
65
+ |---|---|---|
66
+ | Python | **3.11+** | 引擎运行时 |
67
+ | Git | 2.x | diff / worktree 识别 |
68
+ | Bash(Windows 用 Git Bash) | — | 运行 `sandbox/*.sh`(demo / doctor / setup);PowerShell 不自带 `sh`(demo 另有 Python 版) |
69
+ | Node.js(可选) | — | 仅当自定义规则调用 `node` 时需要;示例规则不依赖 |
70
+
71
+ ## 快速开始
72
+
73
+ ### 0. pip 安装(wheel 自带引擎,不需要另 clone 引擎)
74
+
75
+ > **首个 PyPI 版本发布前**:短命令 `pip install guardrail-engine` 仍会 404。发布由 `v*` tag
76
+ > 触发的 `release.yml` 完成(OIDC 可信发布);在那之前请在源码树根目录 `pip install .`
77
+ > (或装本地构建的 wheel)。
78
+
79
+ ```bash
80
+ git clone https://github.com/rain610/guardrail-engine.git
81
+ cd guardrail-engine
82
+ pip install . # 从源码装:wheel 自带引擎
83
+ guardrail-engine init # 把随包引擎落到 ~/.guardrail-engine/engine,并写 ~/.guardrail-engine/harness.path
84
+ guardrail-engine quickstart # 自检 + 打印 MCP 接入配置
85
+ ```
86
+
87
+ `init` 只复制、不删除:目标已存在且内容不同时要求 `--force`,旧目录会改名归档为
88
+ `<dir>.disabled-<时间戳>`;可用 `--dir` 指定引擎安装位置。装完后:
89
+ `guardrail-engine list` 看 gate,`guardrail-engine run <gate> <文件>` 定向检查,
90
+ `guardrail-engine mcp` 启动 MCP 服务。源码树里也可以直接跑 `python guardrail_engine/cli.py init`。
91
+
92
+ ### 1. clone 源码看效果(不需要配置)
93
+
94
+ ```bash
95
+ git clone https://github.com/rain610/guardrail-engine.git
96
+ cd guardrail-engine
97
+
98
+ sh sandbox/demo_gate.sh # 在临时目录造一个 console.log → 拦住 → 改对 → 放行
99
+ python sandbox/demo_gate.py # 同上,且不需要 sh(PowerShell / cmd 直接可用)
100
+ sh sandbox/doctor.sh # 端到端自检:门禁探针 / hook 活性 / skill 软链
101
+ ```
102
+
103
+ > **Windows 需要 Git Bash**:PowerShell / cmd 不自带 `sh`(会报 `无法将"sh"项识别为...`)。
104
+ > `demo` 可直接跑 `python sandbox\demo_gate.py`;`doctor` / `setup` 等 `*.sh` 入口
105
+ > 请在 Git Bash 里执行。
106
+
107
+ `demo_gate.sh` 只写系统临时目录,不碰任何业务仓,也不需要先改配置。它自带两向断言:
108
+ 该拦的必须 `rc=1` 且点名 `NO-CONSOLE`,改对必须 `rc=0`,否则脚本自己以非零退出 ——
109
+ 所以「跑完没报错」是真的验过,而不是演示脚本演了一遍。
110
+
111
+ ### 2. 接入你自己的仓
112
+
113
+ 先让本机有一份本地配置(它被 git 忽略,只影响你这台机器):
114
+
115
+ ```bash
116
+ sh sandbox/setup_machine.sh
117
+ ```
118
+
119
+ 首次运行会从 `config/harness.local.example.toml` 生成 `config/harness.local.toml`,
120
+ 提示你填路径后退出。把内置 `example` gate 指向你的仓 —— **键名 `example_repo` 已在共享
121
+ 配置里声明,本机只填值**:
122
+
123
+ ```toml
124
+ # config/harness.local.toml
125
+ [repos]
126
+ example_repo = "/path/to/your/project"
127
+ ```
128
+
129
+ 然后:
130
+
131
+ ```bash
132
+ # 全量扫一遍
133
+ python harness/run_gate.py example --all
134
+
135
+ # 以后在业务仓里只查本次改动(自动识别 gate)
136
+ cd /path/to/your/project
137
+ python /path/to/guardrail-engine/harness/agents/auto-gate.py
138
+
139
+ # 配置体检:必须 rc=0
140
+ python /path/to/guardrail-engine/harness/run_gate.py --validate
141
+ ```
142
+
143
+ > 不要在本机配置里新增或改写 `[repos]` 的键名。键名是共享 `config/harness.toml` 里的
144
+ > 团队策略,本机只负责填路径;键名不存在时 `--validate` 会 rc=2 —— 这正是「拼错 /
145
+ > 忘了登记」唯一会被发现的时刻。要管多个仓,见「添加新 gate」。
146
+
147
+ ### 3. 定制规则
148
+
149
+ 示例 gate 的规则都在 `checks/example_ruleset.py` 的 `EXAMPLE_RULES` 列表里,
150
+ 改这个列表即可,不需要新建脚本:
151
+
152
+ ```python
153
+ NO_TODO = RegexRule(
154
+ id="NO-TODO",
155
+ pattern=r"\bTODO\b",
156
+ message="禁止 TODO 注释残留",
157
+ fix_hint="实现或删除 TODO",
158
+ )
159
+ ```
160
+
161
+ 把它加进 `EXAMPLE_RULES`,然后回到 guardrail-engine 工程根:
162
+
163
+ ```bash
164
+ cd /path/to/guardrail-engine
165
+ python harness/run_gate.py example --all
166
+ python harness/run_gate.py --validate # 规则 ID / 配置键都会被体检
167
+ ```
168
+
169
+ ### 4. 安装 hooks(可选,推荐)
170
+
171
+ ```bash
172
+ # 提交期 hook(在业务仓根执行;gate 名可省略,按 cwd 自动识别)
173
+ cd /path/to/your/project
174
+ sh /path/to/guardrail-engine/sandbox/install_hooks.sh
175
+
176
+ # 编辑期 hook(给 AI 客户端转发 post-edit 事件)
177
+ python /path/to/guardrail-engine/sandbox/install_shim.py
178
+ ```
179
+
180
+ ## 示例规则
181
+
182
+ 项目自带 3 条示例规则(`checks/example_ruleset.py`),展示如何编写自定义规则:
183
+
184
+ | 规则 ID | 检查内容 | 严重级别 |
185
+ |---|---|---|
186
+ | `NO-CONSOLE` | 代码里的 `console.log` 残留 | block(字符串字面量里降为 warn) |
187
+ | `NO-HARDIP` | 硬编码 IP 地址(每段 ≤255,排除版本号) | block |
188
+ | `EOL-UNIFIED` | 行尾混用 CRLF / LF | block |
189
+
190
+ 运行示例 gate:
191
+
192
+ ```bash
193
+ python harness/run_gate.py example --repo <你的仓> --all
194
+ ```
195
+
196
+ 这些规则是**启发式**,不是生产级解析器。能力边界写在规则集头部,也由自检输出:
197
+
198
+ - 注释里的内容不算命中(`//`、`/* */`、`<!-- -->`、Python `#`);
199
+ - 字符串里的 `console.log` 只提示、不阻断 —— 它可能是日志文案或文档示例;
200
+ - `1.2.3.4` 这类版本号不判 IP(看 `version=` / `v=` 等上下文),非法 IPv4 也不判;
201
+ - 多行块注释的**续行**、跨行字符串不做状态跟踪(单行启发式)。
202
+
203
+ 需要更强的判定时,用 `checks/rule_base.py` 的 `Rule` 子类自己写 `applicable()` / `check()`。
204
+
205
+ ## 黄金范式:拦截之后的下一步
206
+
207
+ 门禁只回答「这行不能这么写」。规则还可以带一条 `see` 指针,把「那该怎么写」送到被拦的那一刻:
208
+
209
+ ```text
210
+ ❌ src/logger.js:3 [NO-CONSOLE] 禁止 console.log 残留(调试代码不应进入提交)
211
+ FIX: 删除 console.log 行,改用统一日志封装(见范式)
212
+ 📖 See: golden-patterns/patterns/cross-cutting/logging.md
213
+ ```
214
+
215
+ 但黄金范式不只是「一条 lint 的修法」。它是一个按任务组织的**代码骨架库**:
216
+
217
+ | 要写什么 | 读哪篇 |
218
+ |---|---|
219
+ | 请求层(token / 响应壳 / 401 / 错误提示) | [`patterns/web/request-layer.md`](golden-patterns/patterns/web/request-layer.md) |
220
+ | 列表页(后端分页 / 筛选 / 批量 / 行操作) | [`patterns/web/list-page.md`](golden-patterns/patterns/web/list-page.md) |
221
+ | 表单弹窗(新增编辑共用 / 校验 / 提交锁) | [`patterns/web/form-dialog.md`](golden-patterns/patterns/web/form-dialog.md) |
222
+ | 后端分层(Controller / Repository / 软删 / 分页) | [`patterns/backend/controller-repository.md`](golden-patterns/patterns/backend/controller-repository.md) |
223
+ | 校验与错误(400/404/500、不吞异常) | [`patterns/backend/validation-and-errors.md`](golden-patterns/patterns/backend/validation-and-errors.md) |
224
+ | 日志 / 配置 | [`logging.md`](golden-patterns/patterns/cross-cutting/logging.md)、[`config-and-env.md`](golden-patterns/patterns/cross-cutting/config-and-env.md) |
225
+ | 从零做一个业务模块 | [`endtoend/task-management.md`](golden-patterns/endtoend/task-management.md) |
226
+
227
+ - 入口:[`golden-patterns/index.md`](golden-patterns/index.md)
228
+ - 参考实现:[`golden-patterns/reference/`](golden-patterns/reference/)(正面样板会跑示例 gate 自证)
229
+ - 造自己的范式:[`golden-patterns/templates/00_范式制造模板.md`](golden-patterns/templates/00_范式制造模板.md)
230
+
231
+ 给规则挂范式只需两步:把**已验收**的写法放进 `golden-patterns/`,在规则类上写
232
+ `see = "golden-patterns/…"`。路径一律仓库相对;规则与范式一起评审 —— 范式是参照系,
233
+ 不是绕过规则的许可。
234
+
235
+ ## 架构
236
+
237
+ ```text
238
+ 客户端提示层 AGENTS.md / skill
239
+ |
240
+ 工具调用层 CLI / MCP / plugin
241
+ |
242
+ 强制拦截层 编辑期 hook + git pre-commit
243
+ |
244
+ 判定引擎 run_gate.py -> checks/*_check.py -> *_ruleset.py
245
+ |
246
+ 台账与体检 reports/gate_log-<YYYY-MM>.jsonl / coverage / doctor
247
+ ```
248
+
249
+ ### 关键目录
250
+
251
+ | 目录 | 职责 |
252
+ |---|---|
253
+ | `checks/` | 规则实现与薄 loader |
254
+ | `harness/` | 调度器、配置读取、hook 入口 |
255
+ | `config/` | gate 与仓库策略 |
256
+ | `integrations/` | 各 AI 客户端接入说明 |
257
+ | `sandbox/` | 安装、自检、打包工具 |
258
+ | `guardrail_engine/` | CLI / MCP 主包(`agentguard/` 是迁移期兼容壳,v0.3 移除) |
259
+ | `tests/` | 单元测试 |
260
+
261
+ ## 规则模型
262
+
263
+ 引擎侧统一基类是 `checks/rule_base.py` 的 `Rule`:
264
+
265
+ ```python
266
+ class Rule:
267
+ id: str
268
+ name: str = ""
269
+ severity_default: Severity = Severity.ERROR
270
+
271
+ def applicable(self, ctx) -> bool: # 该规则是否适用于此文件
272
+ ...
273
+
274
+ def check(self, ctx) -> list[Finding]:
275
+ """返回违规列表"""
276
+ ...
277
+
278
+ def severity(self, ctx) -> Severity: # 双态钩子,默认返回 severity_default
279
+ ...
280
+ ```
281
+
282
+ `checks/example_ruleset.py` 的 `RegexRule` 是同一协议下的正则适配器:
283
+
284
+ ```python
285
+ RegexRule(id, pattern, message, fix_hint="",
286
+ see="", string_severity=None, version_exempt=False, validator=None)
287
+ ```
288
+
289
+ 它和自建规则一样走 `Rule.run(ctx)`:`check(ctx)` 返回 `Finding`,严重级用
290
+ `Severity.ERROR / WARN / INFO`。单条命中需要不同级别时(例如字符串里的
291
+ `console.log` 只提示)直接给 `Finding.severity` 赋值;其余由规则级
292
+ `severity_default` 与存量降级钩子决定。
293
+
294
+ 需要按文件类型收窄、或按上下文判定严重级别时,直接继承 `rule_base.Rule` 并覆写
295
+ `applicable()` / `check()`。`rule_base` 还提供提交期读暂存区(`read_bytes`)、
296
+ 注释区间识别(`comment_spans`)、行内豁免(`inline_waiver`)等公共件。
297
+
298
+ ### 规则类型
299
+
300
+ | 类型 | 适用场景 | 示例 |
301
+ |---|---|---|
302
+ | 单行正则 | 反模式检测 | `console.log`、硬编码 IP |
303
+ | 整文件规则 | 文件级约束 | 行尾混用 |
304
+ | `rule_base.Rule` 子类 | 需要文件类型 / 上下文 / 多态 severity | 自定义 `applicable()` + `severity()` |
305
+
306
+ ## 接外部分析器(ESLint / Semgrep)
307
+
308
+ 内置规则是**示例与兜底**,不是主力分析器。引擎层受「零第三方依赖」约束,标准库里只有
309
+ Python 的 `ast`;Vue / JS / TS / C# 的语法与类型判断交给成熟工具,Guardrail Engine 只负责
310
+ **策略强制**那一层:什么时候跑、跑不过怎么退出、结果怎么进台账、怎么豁免。
311
+
312
+ 两个适配 gate 已注册,默认 `enabled = false`(装了工具、确认配置后再开):
313
+
314
+ ```toml
315
+ [gates.eslint]
316
+ enabled = true # 默认 false;工具没装时开启 = 每次触发 rc=2
317
+ repo = "example_repo" # 指向 [repos] 里的键(本机路径在 harness.local.toml 填)
318
+ script = "checks/eslint_check.py"
319
+ run_on = ["post_edit"] # 默认不挂 pre_commit(原因见下方「已知边界」)
320
+
321
+ [gates.semgrep]
322
+ enabled = false
323
+ repo = "example_repo"
324
+ script = "checks/semgrep_check.py"
325
+ run_on = ["post_edit"]
326
+ ```
327
+
328
+ ```bash
329
+ python harness/run_gate.py eslint --all # 全量:把「.」交给工具按自身配置遍历
330
+ python harness/run_gate.py eslint src/app.js # 定向:只查点名文件
331
+ python harness/run_gate.py semgrep --all
332
+ ```
333
+
334
+ 工具命令默认取 PATH 里的 `eslint` / `semgrep`,可用环境变量覆盖(普通命令或 JSON 数组):
335
+
336
+ ```bash
337
+ export GUARDRAIL_ESLINT='["npx","eslint"]'
338
+ export GUARDRAIL_SEMGREP='["semgrep","scan"]'
339
+ export GUARDRAIL_ADAPTER_TIMEOUT=120 # 秒,默认 300
340
+ ```
341
+
342
+ 外部工具的规则 ID(如 `no-console`、`python.lang.security.audit.eval`)直接可用于
343
+ `harness-ok:` 行内豁免。输出格式、豁免语法、退出码语义与内置规则一致;严重级由工具的
344
+ severity 映射而来(ESLint 1/2;Semgrep 按 CRITICAL/ERROR/HIGH → 阻断,MEDIUM/WARNING →
345
+ 警告,LOW/INFO → 观察,未知级别按阻断处理)。
346
+
347
+ **fail-closed 语义**(这三条是本仓付过学费的地方,锁在 `tests/engine/test_external_adapters.py`):
348
+
349
+ | 情况 | 退出码 | 为什么不能算通过 |
350
+ |---|---|---|
351
+ | 工具没装 / 起不来 / 超时 | `2` | 一条检查都没执行 |
352
+ | 输出不是 JSON / 工具以配置错退出(rc≥2) | `2` | 结论不可信或参数错了 |
353
+ | Semgrep 的 `errors` 非空 | `2` | 有文件没扫完,结果不完整 |
354
+
355
+ `mode` / `legacy_baseline` / `disabled_rules` 对适配 gate **不生效**(`--mode` 旗标会被
356
+ 接收并忽略,台账也不记 `mode_override` —— 适配 gate 没有 strict/loose 可放宽),写上会被
357
+ `--validate` 拒绝:严重级和规则取舍归工具自己的配置文件管
358
+ (`.eslintrc` / `semgrep.yml`),两边各留一个开关只会互相打架。
359
+
360
+ **已知边界**
361
+
362
+ - 外部工具读的是**工作区**文件,提交期门禁不会把暂存区内容喂给它们。因此适配 gate
363
+ **默认只挂 `post_edit`**:挂到 `pre_commit` 后,「暂存坏版本 + 工作区改回好版本」可以
364
+ 绕过它。要用提交期拦截,先在调用方实现暂存副本,或接受工作区语义。
365
+ - 外部 gate **不参与静态规则覆盖度**(`--coverage` 只统计本仓内置规则):规则清单归
366
+ 工具自己的配置管,开启后看到「清单外规则级数据」是正常的。
367
+
368
+ ## 配置
369
+
370
+ 主配置:`config/harness.toml`(Python 3.11+ 标准库 `tomllib` 读取,零第三方依赖)
371
+
372
+ ```toml
373
+ [repos]
374
+ example_repo = "" # 键名留在共享配置;本机路径在 harness.local.toml 填
375
+
376
+ [gates.example]
377
+ enabled = true
378
+ repo = "example_repo"
379
+ script = "checks/example_code_check.py"
380
+ mode = "strict" # strict | loose
381
+ run_on = ["pre_commit", "post_edit"]
382
+ line_ending = "auto" # auto | CRLF | LF
383
+ encoding = "utf-8" # 后端常用 utf-8-bom
384
+ legacy_baseline = false # 存量降级为 info
385
+ disabled_rules = [] # 本 gate 关闭的规则 ID
386
+ ```
387
+
388
+ `gates.<名>.repo` 引用的键**必须先出现在 `[repos]` 段**(`harness_self` 例外:它由引擎注入);
389
+ `config.script` 指向的脚本必须存在。`--validate` 会同时检查这两件事,以及
390
+ `run_on` / `mode` / `line_ending` 等字段的值域;结构通过后还会扫一遍**全部受管仓**的
391
+ `AGENTS.md`(进仓文件不得写指向本引擎的绝对路径)。
392
+
393
+ ### 调度器时限
394
+
395
+ `run_gate` 给门禁子进程设了统一时限(默认 1800 秒):
396
+
397
+ ```bash
398
+ export GUARDRAIL_GATE_TIMEOUT=3600 # 秒;旧名 AGENTGUARD_GATE_TIMEOUT 也认
399
+ ```
400
+
401
+ 超时后**杀掉整棵进程树**并按环境错误返回 `rc=2`,台账记 `timed_out` / `timeout_s` ——
402
+ 「没跑完」不会被读成「通过」。写成非整数或 ≤0 视为配置错(同样 `rc=2`,且不执行 gate)。
403
+
404
+ 业务仓 gate 通过后追加的 AGENTS.md 机器无关性检查**只查本次目标仓**(`--repo`);
405
+ 全舰队扫描在 `--validate` 里做(CI 用 `--validate --structure-only` 时跳过)。
406
+
407
+ ### 本地覆盖层
408
+
409
+ | 优先级 | 来源 | 用途 |
410
+ |---|---|---|
411
+ | 1 | 环境变量 `HARNESS_CONFIG` | CI 或特殊布局 |
412
+ | 2 | `config/harness.local.toml` | 本机仓库路径 |
413
+ | 3 | `config/harness.toml` | 共享基线 |
414
+
415
+ 旧版 `config/harness.local.yaml` / `config/harness.yaml` 仍可被读入(兼容层),
416
+ 但两种格式同时存在时 **TOML 优先**并会在 stderr 提醒;新配置请一律用 TOML。
417
+
418
+ ## 命令速查
419
+
420
+ | 场景 | 命令 |
421
+ |---|---|
422
+ | 列出 gate | `python harness/run_gate.py --list` |
423
+ | 自动检查改动 | `python harness/agents/auto-gate.py` |
424
+ | 定向检查 | `python harness/run_gate.py <gate> <文件...>` |
425
+ | 全量扫描 | `python harness/run_gate.py <gate> --all` |
426
+ | 配置体检(含全舰队 AGENTS.md 检查) | `python harness/run_gate.py --validate` |
427
+ | 60 秒演示(无需 sh) | `python sandbox/demo_gate.py` |
428
+ | 运行摘要 | `python harness/run_gate.py --summary` |
429
+ | 覆盖度报告 | `python harness/run_gate.py --coverage` |
430
+ | 台账核链 + 引擎归因 | `python guardrail_engine/cli.py log --verify --engine` |
431
+ | 安装提交 hook | `sh sandbox/install_hooks.sh <gate>` |
432
+ | 安装编辑期 hook | `python sandbox/install_shim.py` |
433
+ | 接入自检 | `sh sandbox/doctor.sh` |
434
+ | 快速测试 | `python sandbox/run_tests.py --fast` |
435
+ | 全量测试 | `python sandbox/run_tests.py --full` |
436
+ | 紧急旁路(留痕) | `python guardrail_engine/cli.py bypass --repo <端仓> --reason "≥10 字的原因"` |
437
+
438
+ > `bypass` 只是**声明留痕入口,不是权限闸**:它不拦任何提交,也不改变门禁判定。
439
+
440
+ ## 退出码
441
+
442
+ | 退出码 | 含义 | 处理 |
443
+ |---|---|---|
444
+ | `0` | 通过 | 继续 |
445
+ | `1` | 门禁拦截 | 按输出修复 |
446
+ | `2` | 配置 / 调用错误(含点名的目标文件不存在、不可读) | 检查配置与传入的文件 |
447
+ | `3` | 非受管仓库 | 跳过 |
448
+
449
+ ## 审计证据强度
450
+
451
+ `sandbox/audit_reconcile.py` 拿台账对照提交历史,匹配用的是**时间窗**而不是提交内容指纹。
452
+ 因此它的产物是**线索级**证据:只能说明"提交前后本机跑过同一 gate 且通过",不能证明
453
+ "这次提交的内容被检查过"。
454
+
455
+ - 可用于人工复核与追责线索;
456
+ - **不要写成**"提交可自证",也不要对外宣称已满足强制审计。
457
+
458
+ 台账里另有一层**引擎内容**指纹(见下一节 `Engine-Sha`):它能说明"这条判定用的是哪份
459
+ 门禁代码",但那是台账自身的归因,不是"这次提交的内容被检查过"的证明。
460
+
461
+ ## 保护边界(防 AI 改门禁)
462
+
463
+ `[harness]` 提交标记只是**变更声明**,不是权限边界:任何人在本地都能写这句。
464
+ 真正的强制层是仓库侧配置:
465
+
466
+ - `.github/CODEOWNERS` 把 `checks/`、`harness/`、`guardrail_engine/`、`agentguard/`、`config/`、
467
+ `sandbox/mutation_smoke.py`、`tests/tooling/test_lock_inventory.py`、`tests/lock-inventory.json`
468
+ 与 `.github/` 指给维护者;
469
+ - 在 GitHub 的 **Settings → Branches → Branch protection rules** 里给 `main` 开启
470
+ **Require a pull request before merging** 与 **Require review from Code Owners**。
471
+ 只提交 CODEOWNERS 而不开分支保护,规则只会「请求 review」,不会阻断合并;
472
+ - 本仓的 commit-msg hook 会拦「改了受保护文件但提交消息没有 `[harness]`」——它挡的是
473
+ 误操作;有意绕过的人不受它约束。边界仍是上面的 CODEOWNERS + 分支保护。
474
+
475
+ ### 引擎内容的可追溯性(Engine-Sha)
476
+
477
+ `[harness]` 只说明"这次改了门禁",不说明"改成了什么内容"。台账每条记录都带
478
+ `engine_sha`(引擎内容的 16 位哈希),但**不能**直接拿它跟「当前引擎」比 —— 正常升级、
479
+ 甚至改一行测试锁都会让当前值变,那样每次升级全本都会红。
480
+
481
+ 内容面 = `checks/` + `harness/` + `guardrail_engine/` + `agentguard/` + 配置 / 变异冒烟 /
482
+ 锁清单。壳包的 `run` / `done` / `log --verify` / `hooks` / `mcp` 会产出判定与凭证,
483
+ 所以和规则本身一样计入哈希。
484
+
485
+ 本仓的口径是**提交归因**:
486
+
487
+ 1. 带 `[harness]` 的提交,在提交消息末尾加一行 `Engine-Sha: <16 位哈希>`;值来自
488
+ `python harness/run_gate.py --engine-sha`(只读出口,配置坏了也能回答);
489
+ 2. CI 的 `provenance` job 会按该提交的内容**重算**并与尾注比对,不一致即失败;
490
+ 3. `python guardrail_engine/cli.py log --verify --engine` 把台账里的 `engine_sha` 与
491
+ **提交历史里声明过的集合**对账,基线是第一条带尾注的提交时间,更早的历史不追溯。
492
+
493
+ 会红的是「记录用的引擎内容从未被提交」—— 这正是"瞬时改弱规则 → 跑通过 → 改回 → 提交"
494
+ 留下的形状。开发期用未提交的引擎跑门禁也会落在清单里:把那份引擎提交并补尾注,
495
+ 或重跑一次已提交引擎即可。核对不通过只影响这条读命令,不反向拦门禁。
496
+
497
+
498
+ ## 扩展
499
+
500
+ ### 添加新规则
501
+
502
+ 1. 在 `checks/example_ruleset.py` 的 `EXAMPLE_RULES` 里加一条 `RegexRule(...)`;
503
+ 自建规则集则在检查脚本里改 import
504
+ 2. `python harness/run_gate.py example --all` 试跑
505
+ 3. `python harness/run_gate.py --validate` —— 规则 ID、配置键都会体检
506
+
507
+ 需要现成的编码约定规则集?见下文《自带的可选规则集:编码卫生》
508
+ ([checks/encoding_ruleset.py](checks/encoding_ruleset.py))—— 它是给你自己的检查脚本用的库,
509
+ 默认不注册 gate。
510
+
511
+ ### 添加新 gate(多仓 / 独立规则集)
512
+
513
+ 四处都要动,少一处的症状是「看起来配好了」:
514
+
515
+ 1. **共享** `config/harness.toml` 的 `[repos]` 段加键名(值 `""`)—— 键名是团队策略,
516
+ 与机器无关
517
+ 2. **共享** `config/harness.toml` 的 `[gates.<名>]` 表加 gate,`repo =` 指向该键,`script =`
518
+ 指向检查脚本。新脚本可从 `checks/example_code_check.py` 复制,把
519
+ `from example_ruleset import ...` 换成自己的 ruleset
520
+ 3. `checks/registry.py` 登记**两处**:`ENDPOINT_SCRIPTS`(端名 → 脚本路径)与
521
+ `RULESETS`(脚本 basename → ruleset 模块名)。只登第一处、漏了 `RULESETS`,
522
+ 门禁仍能跑,但 `--coverage` 和 `harness_self` 的能力边界清单看不到这套规则 ——
523
+ 又回到「静默盲区」。未登记时会走 `config.script` 兜底,`--validate` 只提示、不算失败
524
+ (外部适配 gate 不经过本仓规则集,`RULESETS` 里没有它们是**正常状态**)
525
+ 4. **本机** `config/harness.local.toml` 的 `[repos]` 里填该键的路径(只有这一步是本机的)
526
+
527
+ 最后跑:
528
+
529
+ ```bash
530
+ python harness/run_gate.py --validate # 必须 rc=0
531
+ python sandbox/run_tests.py --fast
532
+ ```
533
+
534
+ ### 自带的可选规则集:编码卫生(`checks/encoding_ruleset.py`)
535
+
536
+ 这个模块是**给你自己的检查脚本用的库**,默认不注册成 gate —— 编码约定是每个仓自己的
537
+ 事实(.NET 仓常见 `utf-8-bom`,前端仓 `utf-8`),给一个全局默认会把另一类仓整片报红。
538
+
539
+ 它解决的是"AI 跟随异类文件的编码写入":往一个 GBK 的老 `Program.cs` 追加代码,
540
+ diff 会变乱码。判定分两档:本次**改动过或新建**的文件编码不符 = 拦截;全量扫描里的
541
+ 存量异类 = 只报告。
542
+
543
+ 接线方式(照「添加新 gate」的四步做,脚本里换成这个规则集):
544
+
545
+ ```python
546
+ import rule_base
547
+ from encoding_ruleset import rules_for
548
+
549
+ raw = rule_base.read_bytes(filepath) # 走暂存区读取,别直接 open()
550
+ ctx = rule_base.CheckContext(path=..., rel=rel, raw=raw,
551
+ content=raw.decode("utf-8", errors="replace"),
552
+ repo=repo, mode=a.mode or "strict",
553
+ targeted=(scope == "targeted"))
554
+ for rule in rules_for("utf-8-bom"): # 取值跟仓约定走,别照抄
555
+ for f in rule.run(ctx):
556
+ ...
557
+ ```
558
+
559
+ 两个容易漏的点:`raw=` 必须传原始字节(规则判的是字节,不是解码后的文本);
560
+ 定向口径要把 `targeted=True` 传进来 —— 缺了它 `error_in_targeted` 不生效,规则最重
561
+ 只到 info(看起来装了这条规则,却从不拦提交)。
562
+
563
+ ### 行内豁免
564
+
565
+ 合规写法被规则误报时,在命中行或紧邻上一行的**注释**里写标记:
566
+
567
+ ```js
568
+ // harness-ok: NO-CONSOLE 调试日志已用条件封装
569
+ if (DEBUG) console.log("debug info")
570
+ ```
571
+
572
+ - 行内豁免:`harness-ok: <规则ID> <理由>`(适用端:示例 gate)
573
+ - 字符串字面量里的标记不算;规则 ID 必须写对,理由必填。
574
+ - 规则集通过 `rule_base.inline_waiver()` 接入同一判据。
575
+
576
+ ## 与 AGENTS.md 的关系
577
+
578
+ | 层 | 负责什么 |
579
+ |---|---|
580
+ | `AGENTS.md` | 架构意图、业务语义、红线与人工判断 |
581
+ | `Guardrail Engine` | 可机械判定的规则、自动触发、台账与验收 |
582
+
583
+ 只写 `AGENTS.md` 成本最低,但没有强制力;加 Guardrail Engine 后才能在编辑期和提交期获得机械拦截与留痕。
584
+
585
+ ## 支持的 AI 客户端
586
+
587
+ | 客户端 | 接入方式 |
588
+ |---|---|
589
+ | Claude Code | AGENTS.md + hooks |
590
+ | Codex | AGENTS.md + hooks |
591
+ | OpenCode | AGENTS.md |
592
+ | CodeBuddy | AGENTS.md |
593
+ | Trae CN | AGENTS.md |
594
+ | Qoder CN | AGENTS.md |
595
+ | ZCode | AGENTS.md |
596
+ | 其他 MCP 宿主 | MCP 服务 |
597
+
598
+ ## 测试
599
+
600
+ ```bash
601
+ # 快速测试(编辑回路;跳过真打包/真安装/真 git 链路;本机约 1.5-8 分钟,视机器与并行度)
602
+ python sandbox/run_tests.py --fast
603
+
604
+ # 全量测试(提交前/CI;含真打包/真安装/真 git 链路)
605
+ python sandbox/run_tests.py --full
606
+
607
+ # 单元测试
608
+ python -m unittest discover -s tests
609
+ ```
610
+
611
+ 发布链(`.github/workflows/release.yml`)与每日定时(`.github/workflows/nightly.yml`)
612
+ 还会跑三类慢闸门:变异冒烟(114 条变异,验证锁真的会红)、真打包后的真产物锁、
613
+ 干净 venv 安装并执行 `guardrail-engine --version`(轮子自带引擎,不依赖引擎检出)。
614
+ 本机复现:先 `python sandbox/pack_release.py`,再跑
615
+ `python tests/packaging/test_release_artifact.py TestRealArtifactPasses -v`;venv 安装命令见
616
+ `.github/workflows/release.yml` 的「干净 venv 安装冒烟」步骤。
617
+
618
+ ## 文档
619
+
620
+ | 文档 | 内容 | 英文版 |
621
+ |---|---|---|
622
+ | [CONTRIBUTING.md](CONTRIBUTING.md) | 贡献指南:如何加一条规则并让它过变异冒烟 | — |
623
+ | [SECURITY.md](SECURITY.md) | 安全策略:漏洞报告通道与已知限制 | — |
624
+ | [docs/THREAT-MODEL.md](docs/THREAT-MODEL.md) | 威胁模型:信任边界、攻击面、tamper-evident 设计取舍 | [EN](docs/THREAT-MODEL.en.md) |
625
+ | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | 行为准则(Contributor Covenant 2.1) | — |
626
+ | `docs/packaging/INSTALL.md` | 安装、升级、卸载 | [EN](docs/packaging/INSTALL.en.md) |
627
+ | `docs/packaging/RUNBOOK.md` | 日常排障、回滚、对账 | [EN](docs/packaging/RUNBOOK.en.md) |
628
+ | `docs/packaging/COMPAT.md` | 客户端兼容矩阵 | [EN](docs/packaging/COMPAT.en.md) |
629
+ | `docs/adr/` | 架构决策记录 | — |
630
+ | `AGENTS.md` | agent 工程地图 | — |
631
+
632
+ ## 许可证
633
+
634
+ MIT License - 详见 [LICENSE](LICENSE)
635
+
636
+ ## 贡献
637
+
638
+ 欢迎提交 Issue 和 Pull Request。贡献前请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)(重点:如何加一条规则并让它过变异冒烟)。
@@ -0,0 +1 @@
1
+ 0.2.0