@yottameta/yotta-guardian 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 更新日志
 
+## v0.1.7 (2026-09-28)
+
+文档格式修复 + 两处引擎健壮性修复（规则判定行为不变）。
+
+- **修复代码围栏**：`SKILL.md` 与 `references/`（intent-verifier / policies / rules）中被写作管线占位符顶替的代码围栏，全部还原为标准三个反引号，共 20 处；此前自 0.1.0 起一直未还原，Markdown 渲染异常（命令与配置示例无法按代码块显示）。
+- **修复非法转义（0.1.0 起既有）**：`scripts/guardian_rules.py` 的模块 docstring 里 `\s`、`\b` 属非法转义 —— Python 3.12+ 每次调用都向 stderr 报 2 行 SyntaxWarning，严格告警（`PYTHONWARNINGS=error`）下引擎直接加载失败。该 docstring 改为 raw 字符串（与规则表内 `r"…"` 写法一致），告警消失。
+- **修复致命异常退出码（fail-closed，0.1.0 起既有）**：此前未捕获异常走 Python 默认退出码 1，而契约里 1 = 允许但带警告 —— 按退出码判定的宿主会把「引擎崩溃」读成放行（fail-open）。现在规则表加载失败与运行期未预期异常统一以**退出码 4**（用法错误 / 致命异常）结束并在 stderr 写明原因；新增 3 项回归用例（导入失败 → 4、运行期异常 → 4、严格告警下仍正常判定，共 86 项）。
+- **修复彩色输出必崩（0.1.6 起既有）**：`check` 的彩色分支 `c()` 格式串只有 1 个 `%s` 却喂 2 个参数 —— 真人终端（`sys.stdout.isatty()` 为真）必抛 `TypeError`，以退出码 4 结束且**判定与命中规则完全不输出**；`--json` / `--no-color` / 管道不受影响（故此前测试未覆盖）。已修正格式串，并新增「假 TTY」回归用例（共 88 项）。
+- **文档**：`SKILL.md` 新增「宿主接入」一节（放行不代批 / 用文件接引擎输出 / stdin 按 UTF-8 读），并把退出码 4 的语义写成「用法错误 / 致命异常（绝不要当作放行）」。
+- **发布门禁联动**：`validate-skill` 与 `preflight-publish` 的交付面检查扩到 Python 一侧（语法错误 / 非法转义等编译期告警），与 Markdown 检查共用同一入口，命中即拦。
+- 规则判定、策略档位、CLI 输出结构与审计格式不变；版本四处对齐 0.1.7。
+
 ## v0.1.6 (2026-09-25)
 
 安全修复：复合命令拆分，堵住分隔符后的危险段绕过。
@@ -50,7 +62,7 @@
 
 - **README.md 改为英文**：作为 GitHub / npm / ClawHub 首页的英文门面（翻译 + 精简，覆盖定位 / 核心价值 / 命令 / 快速使用 / 安装 / 使用示例 / 边界 / 开发校验全流程）。
 - **新增 README.zh-CN.md**：原中文完整主文档整体平移，顶部加语言切换链接。
-- **修复代码围栏**：README 中 `_BT_`bash / `_BT_` 占位符全部改为标准 ```bash / ```（Markdown 渲染修复）。
+- **修复代码围栏**：README 中的围栏占位符（写作管线留下的标记）全部改为标准 ```bash / ```（Markdown 渲染修复）。
 - **package.json**：description 改英文；files 加 README.zh-CN.md；版本 0.1.0 → 0.1.1。
 - 版本四处对齐：package.json / SKILL frontmatter / 引擎 VERSION / 文档。
 - 边界（B 方案）：references / CHANGELOG / 测试注释不翻译；SKILL 触发描述保持中文。

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-guardian
-version: 0.1.6
+version: 0.1.7
 description: 元盾 —— 跨智能体的危险调用拦截护栏：确定性规则引擎 + 可插拔意图验证（不绑模型），拦截危险 exec / write / edit / read / run / shell 工具调用，提供审计日志。触发：代理要执行高风险命令（递归删除、磁盘格式化、提权、防火墙改动、反向 shell、下载即执行等）、要写入系统敏感路径或修改系统配置、要在执行危险操作前做安全检查、或用户说 护栏/拦截/危险操作/安全检查 等。边界：默认只读评估，不自动执行也不放行危险操作；不替代用户决策；不隐藏审计记录；规则可配置。
 license: MIT
 ---
@@ -27,7 +27,7 @@ license: MIT
 
 Windows 用 python，Linux/macOS 用 python3。
 
-`_BT_`bash
+```bash
 # 检查一条 exec（0 = 允许）
 python3 scripts/yotta_guardian.py check exec --cmd "git status"
 
@@ -43,15 +43,25 @@ python3 scripts/yotta_guardian.py check --batch calls.json --json
 # 审计
 python3 scripts/yotta_guardian.py check exec --cmd "..." --audit-log .yotta-guardian/audit.jsonl
 python3 scripts/yotta_guardian.py audit --file .yotta-guardian/audit.jsonl --tail 20
-`_BT_`
+```
 
 ## 工作流程（AI 智能体执行危险操作前）
 
 1. **先检查**：把将要执行的工具调用交给护栏 `check`（单条或 `--batch` 批量）。
-2. **看退出码**：0 = 允许；1 = 允许但带警告（建议人工复核）；2 / 3 = 拒绝（high / critical，不要执行）；4 = 用法错误。
+2. **看退出码**：0 = 允许；1 = 允许但带警告（建议人工复核）；2 / 3 = 拒绝（high / critical，不要执行）；4 = 用法错误 / 致命异常（引擎没跑起来 —— 绝不要当作放行）。
 3. **被拒绝怎么办**：如实向用户报告原因与命中规则；确有授权的操作，用 `--allow` / `--allow-path` / 自定义规则文件放行并留审计记录；**不要绕过检查**。
 4. **留痕**：高风险场景用 `--audit-log` 落审计日志，供追溯。
 
+## 宿主接入（把护栏挂到「工具调用前」事件时）
+
+`skill-manifest.json` 声明 `before_tool` + `fallback: explicit-unverified`。接入方按下面三条做，可避开实测踩过的坑：
+
+1. **放行不要回「允许」**：只在拦截时输出拒绝判定（如 `permissionDecision: "deny"`）；放行时**不输出任何判定**，把决定权交回宿主。若放行时回「allow」，会覆盖宿主自身的权限流程，护栏就变成自动放行器 —— 护栏只该「拦」，不该「代批」。
+2. **用文件接引擎输出**：部分 hook 进程环境里，用管道捕获子进程 stdout 会拿到空值（同一写法跑 `python -c "print(1)"` 却正常）；把引擎 stdout / stderr 重定向到临时文件再读回，判定即稳定（引擎自身的 stdout 是纯净的，`--json` 可直接解析）。
+3. **stdin 先按 UTF-8 读**：hook 载荷里的命令文本常含中文，按本机默认码页解码会乱码；读 stdin 前先 `sys.stdin.reconfigure(encoding="utf-8")`（引擎已对自身 stdout / stderr 做 UTF-8 处理，stdin 由接入方负责）。
+
+另外：引擎对「没跑起来」是 fail-closed 的 —— 规则表加载失败或运行期未预期异常一律以退出码 4 结束并在 stderr 写「致命异常: …」。接入方应把 4 当作**不放行 + 报告**处理，而不是放行。
+
 ## 策略（policy）
 
 | 策略 | 行为 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-guardian",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Yuandun (元盾) — cross-agent dangerous tool-call guardrail: a deterministic rule engine + pluggable intent verifier (model-agnostic) that evaluates exec/write/edit/read/run/shell calls and provides audit logs. Triggers when an agent is about to run a high-risk command, write sensitive paths, or change system config. Boundaries: read-only evaluation by default, configurable allowances.",
   "license": "MIT",
   "keywords": [

package/references/intent-verifier.md

@@ -13,7 +13,7 @@
 
 引擎对「允许」结论的调用发起验证，写入 stdin 的 JSON：
 
-`_BT_`json
+```json
 {
   "tool": "exec",
   "cmd": "npm install",
@@ -24,19 +24,19 @@
   "cwd": "/home/user/project",
   "findings": []
 }
-`_BT_`
+```
 
 字段说明：tool 为工具类型；cmd / path / content_preview（内容前 500 字符）/ target 为调用内容；policy 为当前策略；findings 为确定性规则已命中的条目（允许结论下通常为空或仅低危）。
 
 ## 三、响应（stdout，JSON）
 
-`_BT_`json
+```json
 {
   "verdict": "allow",
   "severity": "low",
   "reason": "安装依赖，无恶意信号"
 }
-`_BT_`
+```
 
 - verdict：allow / deny / review 三选一（必须）。
 - severity：可选，deny 时默认 high；取值 info / low / medium / high / critical。
@@ -59,7 +59,7 @@
 
 ## 六、示例验证器（Python 桩）
 
-`_BT_`python
+```python
 #!/usr/bin/env python3
 import json
 import sys
@@ -71,6 +71,6 @@ if cmd.startswith("danger"):
 else:
     out = {"verdict": "allow", "severity": "low", "reason": "无风险信号"}
 json.dump(out, sys.stdout)
-`_BT_`
+```
 
 真实场景可用该协议把调用摘要发给 LLM 网关做语义判断，返回同样的 JSON 即可接入。

package/references/policies.md

@@ -34,9 +34,9 @@ AI 智能体判断：退出码非 0 时不要直接执行；2 / 3 一律停下
 
 ### 执行前 gate
 
-`_BT_`bash
+```bash
 python3 scripts/yotta_guardian.py check exec --cmd "<待执行命令>" --json
-`_BT_`
+```
 
 - exit 0：执行。
 - exit 1：执行但提示用户「护栏给出中危警告」。
@@ -45,9 +45,9 @@ python3 scripts/yotta_guardian.py check exec --cmd "<待执行命令>" --json
 
 ### 批量预检
 
-`_BT_`bash
+```bash
 python3 scripts/yotta_guardian.py check --batch calls.json --json
-`_BT_`
+```
 
 calls.json 为数组或 {"calls": [...]}，每项含 tool / cmd / path / content / old / new / target。任一被拒时整体退出码取最严重值。
 
@@ -55,25 +55,25 @@ calls.json 为数组或 {"calls": [...]}，每项含 tool / cmd / path / content
 
 确有授权的操作（如正规重启、备份清理）用显式放行，而不是绕过检查：
 
-`_BT_`bash
+```bash
 python3 scripts/yotta_guardian.py check exec --cmd "<命令>" --allow "<模式>"
 python3 scripts/yotta_guardian.py check write --path "<路径>" --allow-path "<前缀>"
-`_BT_`
+```
 
 ### 审计
 
-`_BT_`bash
+```bash
 # 检查时落审计
 python3 scripts/yotta_guardian.py check exec --cmd "<命令>" --audit-log .yotta-guardian/audit.jsonl
 
 # 查询
 python3 scripts/yotta_guardian.py audit --file .yotta-guardian/audit.jsonl --tail 20
 python3 scripts/yotta_guardian.py audit --file .yotta-guardian/audit.jsonl --denied --json
-`_BT_`
+```
 
 ## 五、JSON 输出结构（check --json）
 
-`_BT_`json
+```json
 {
   "tool": "yotta-guardian",
   "version": "0.1.0",
@@ -93,4 +93,4 @@ python3 scripts/yotta_guardian.py audit --file .yotta-guardian/audit.jsonl --den
     }
   ]
 }
-`_BT_`
+```

package/references/rules.md

@@ -101,7 +101,7 @@
 
 ## 六、自定义规则文件（--config）
 
-`_BT_`json
+```json
 {
   "policy": "default",
   "allow": ["^git "],
@@ -109,7 +109,7 @@
   "deny": ["^evil"],
   "verifier": { "command": ["python3", "/path/verifier.py"], "timeout": 30 }
 }
-`_BT_`
+```
 
 - policy: default / strict / loose
 - allow: 命令正则放行模式

package/scripts/guardian_rules.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""guardian_rules.py — YottaMeta 元盾（yotta-guardian）内置规则表（数据，不含匹配逻辑）。
+r"""guardian_rules.py — YottaMeta 元盾（yotta-guardian）内置规则表（数据，不含匹配逻辑）。
 
 本文件只声明规则数据，与 yotta-security-audit（元安）/ yotta-vetter（元审）的
 「源码静态扫描」规则不同：这里是「工具调用护栏」规则，面向 exec / write / edit 等

package/scripts/yotta_guardian.py

@@ -49,9 +49,15 @@ except Exception:
 
 _HERE = Path(__file__).resolve().parent
 sys.path.insert(0, str(_HERE))
-import guardian_rules as GR  # noqa: E402
+try:
+    import guardian_rules as GR  # noqa: E402
+except BaseException as _import_exc:  # 规则表加载失败 = 引擎没跑起来 → 致命异常（4）
+    sys.stderr.write(
+        "致命异常: 规则表加载失败: %s: %s\n" % (type(_import_exc).__name__, _import_exc)
+    )
+    raise SystemExit(4)
 
-VERSION = "0.1.6"
+VERSION = "0.1.7"
 TOOL_NAME = "yotta-guardian"
 TOOL_CN = "元盾"
 
@@ -1138,7 +1144,8 @@ def _build_verifier(args):
 
 def _print_check_text(call, verdict, color):
     def c(s, code):
-        return "\033[%sm\033[0m" % (code, s) if color else s
+        # 2026-09-28：原写法只有 1 个 %s 却喂了 2 个参数 → 彩色路径（真人终端）必崩 TypeError。
+        return "\033[%sm%s\033[0m" % (code, s) if color else s
     kind = c("DENY", "31;1") if not verdict.allowed else c("ALLOW", "32;1")
     sev = verdict.severity.upper()
     print("[检查]  %s" % call.describe(300))
@@ -1367,4 +1374,16 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    main()
+    # 顶层兜底（2026-09-28）：未捕获异常一律按「致命异常」退出码 4 结束。
+    # 绝不能让引擎崩溃落到 1 —— 契约里 1 = 允许但带警告，按退出码判定的宿主会把
+    # 「护栏没跑起来」读成放行（fail-open）。SystemExit / KeyboardInterrupt 原样透传。
+    try:
+        main()
+    except (SystemExit, KeyboardInterrupt):
+        raise
+    except BaseException as exc:  # 兜底就是要 catch-all
+        try:
+            sys.stderr.write("致命异常: %s: %s\n" % (type(exc).__name__, exc))
+        except Exception:
+            pass
+        raise SystemExit(4)

package/skill-manifest.json

@@ -3,7 +3,7 @@
   "slug": "yotta-guardian",
   "name": "元盾",
   "package": "@yottameta/yotta-guardian",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "trust": "yottameta",
   "install": {
     "idempotent": true