# MoonAnsi Guard 演示脚本

这份脚本用于比赛初审、项目验收或录屏讲解。推荐控制在五到十分钟内，重点展示项目不是简单 demo，而是一个有边界、有 API、有示例、有测试的安全审计库。

## 一句话介绍

MoonAnsi Guard 是一个用 MoonBit 编写的终端控制序列安全清洗与审计库。它可以把来自 AI Agent、CI、远程命令或日志系统的不可信终端输出，转换成可安全展示的文本，并同时给出结构化风险记录、风险等级、风险分数和可读审计报告。

## 演示命令

```powershell
cd D:\Moonbit\projects\moonansi-guard
D:\Moonbit\bin\moon.exe run cmd/main
```

先用一条命令展示实际审计能力：

```powershell
D:\Moonbit\bin\moon.exe run cmd/audit -- --escaped "build ok\e]52;c;secret\a done"
```

预期重点输出为 `risk: high`、`action: block`、`safe text: build ok done`，以及一条 `clipboard_write` 命中记录。

主演示会覆盖：

- 彩色构建日志；
- OSC 52 剪贴板写入；
- OSC 8 隐藏超链接；
- OSC 0／2 窗口标题伪装；
- CSI 光标移动和清屏改写；
- 回车与退格日志改写；
- DCS 私有终端负载；
- 截断控制序列；
- strict／styled 策略对比；
- 可读审计报告输出。

## 接入示例

### 跨分块流式审计

```powershell
D:\Moonbit\bin\moon.exe run examples/stream-audit
```

讲解重点：OSC 52 被拆成多个数据块后仍被识别；最终输出全局偏移、风险统计、门禁原因和 JSON 报告。

### 门禁策略对比

```powershell
D:\Moonbit\bin\moon.exe run examples/policy-gate
```

讲解重点：相同日志在严格、均衡和宽松策略下得到不同的 `allow`、`review`、`block` 决策。

### CI 安全门禁

```powershell
D:\Moonbit\bin\moon.exe run examples/ci-gate
```

讲解重点：CI 平台可以把高风险终端输出标记为需要安全复核，同时仍然保存清洗后的日志。

### AI Agent 工具输出

```powershell
D:\Moonbit\bin\moon.exe run examples/agent-output
```

讲解重点：Agent 不应该把 shell 原始输出直接拼给用户，而应该只展示清洗后的文本，并保留审计元数据。

## 验证命令

```powershell
D:\Moonbit\bin\moon.exe build
D:\Moonbit\bin\moon.exe test
```

验收时可以展示 91 项测试和全部通过结果，证明项目不是只写了一个演示程序。

## 推荐讲法

1. 现在很多 AI Agent、CI 和远程命令都会生成终端输出，但这些输出并不总是安全的。
2. 终端控制序列不只影响颜色，还可能修改标题、隐藏链接、写入剪贴板、移动光标、清屏或伪造日志。
3. MoonAnsi Guard 的输入是一段不可信字符串，输出是安全文本和结构化审计结果。
4. 项目不仅提供 `sanitize`，还提供风险分类、风险计数、风险分数、风险等级和可读审计报告。
5. 项目边界很清楚：它不是终端模拟器，也不执行命令，只做清洗、分类和审计。
6. 因此它容易嵌入日志系统、CI、聊天机器人、AI Agent 框架和自动化测试工具。

## 重点展示的输出字段

- `text()`：安全文本；
- `findings()`：结构化风险列表；
- `sequence_preview()`：可读控制序列预览；
- `dangerous_count()`、`warning_count()`、`info_count()`：严重级别统计；
- `risk_score()`：风险分数；
- `risk_level()`：风险等级；
- `audit_report()`：可读审计报告。
- `json_report_with()`：完整、限长或脱敏的机器报告；
- `StreamScanner`：跨分块状态和全局偏移；
- `decide_with()`、`decision_reasons()`：自动化门禁与可解释原因。