---
name: "engineering-memory-guardrails"
description: "工程记忆与防踩坑军规库"
---

# 工程记忆与防踩坑军规库

## 适用场景
在跨会话开发、前后端联调、移动端适配、跨境海外网络环境部署、Nginx 反向代理配置与 Windows/Linux 跨平台脚本编写时，指导 AI 严格调用过往沉淀的真实工程“防踩坑铁律”，坚决避免在移动端点击失效、Cloudflare 403 阻断、编码乱码、端口冲突、后台进程僵死等同类问题上重蹈覆辙。

## 功能说明
> 很多 AI 助手“每次会话都是一张白纸”，上一次刚修好的跨域问题、特定环境编码坑，下一次会话又全忘光、重新犯相同的错误。本技能将团队血泪教训沉淀为确定性工程守则（Engineering Invariants），在代码生成与部署前进行强制自检拦截。

## 这个案例能帮你做什么
- 沉淀高频踩坑规则库（覆盖 Web 前端、服务端反向代理、Windows 终端编码、网络反爬防御等核心痛点）。
- 代码生成前强制触发“军规自检”：若发现包含已被拉黑的错误写法（如移动端使用未经处理的 `target="_blank"`、Windows 脚本未指定 UTF-8 导致中文乱码等），立即主动拦截并给出防御性修复。
- 支持跨会话记忆提取与“错题本（Post-Mortem Ledger）”沉淀机制：每次遇到新 Bug 解决后，自动提取一条抽象规则归档进军规库。

## 你需要的 Skills（按类型）

| 类型 | Skill / 工具 | 用途 | 来源 |
|---|---|---|---|
| 规则匹配 | 预检查正则表达式 / AST Lint | 扫描生成代码中的易踩坑特征 | Built-in |
| 记忆存储 | `MEMORY.md` / `guardrails.json` | 跨会话沉淀不可触碰的工程军规 | Built-in |
| 内置 | `filesystem` | 读写工程记忆与规范文档 | Built-in |

## 快速体验版（先跑一轮）

```text
你是顶级软件架构总监与代码审查委员会主席。
请调取“工程防踩坑军规库”，对以下一段开发需求与配置进行预检：
需求：需要为一个海外电商网页添加商品外部跳转链接，并通过 Python 脚本调用 Cloudflare 保护的 API 接口拉取数据。
请输出：
1. 针对移动端 Web 跳转与触摸响应的防御军规（如 touch-action 与 target blank 处理）。
2. 针对 Cloudflare 保护接口的请求头合规军规（防止裸奔触发 403 WAF 拦截）。
3. Windows 运行环境下 Python 脚本输出中文时的编码必设项。
```

## 稳定自动版（可长期运行）

### 1) 核心工程军规清单 (`guardrails.md`)

```markdown
# 核心工程防踩坑军规（绝对红线）

## 1. Web 交互与移动端体验
- **军规 1.1**：移动端所有外链跳转 `target="_blank"` 必须附带 `rel="noopener noreferrer"`，且在触摸交互组件上强制显式声明 CSS `touch-action: manipulation;`，杜绝 iOS Safari 300ms 点击延迟与幽灵点击。
- **军规 1.2**：弹窗与抽屉（Drawer）打开时，必须锁定底层 `body` 滚动（`overflow: hidden`），并在弹窗关闭时百分百还原滚动位置。

## 2. 网络请求与 Cloudflare 防御
- **军规 2.1**：请求受 Cloudflare 保护的接口时，严禁使用 Python `requests` 默认的裸 User-Agent（否则直接 403）。必须注入完整现代浏览器头部（包含 `Sec-Ch-Ua`, `Sec-Fetch-Dest`, `Accept-Language`）。
- **军规 2.2**：Nginx 反向代理向后端传递客户端真实 IP 时，必须配置 `proxy_set_header X-Real-IP $remote_addr;` 与 `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;`，杜绝后端日志全显示 127.0.0.1。

## 3. Windows 环境脚本与编码
- **军规 3.1**：所有 Windows `.bat` / `.cmd` / `.ps1` 脚本若包含中文字符，头部必须先执行 `chcp 65001 >nul`，Python 脚本必须加入 `sys.stdout.reconfigure(encoding='utf-8')`，严禁让终端在 GBK 乱码下崩溃。
- **军规 3.2**：Windows 下杀后台常驻进程时，严禁生硬使用 `taskkill /F /PID` 导致子进程成为孤儿进程，必须带上 `/T` 参数树形清理（`taskkill /F /T /PID`）。
```

### 2) 自动化代码防御性审查工具 (`guardrails_linter.py`)

```python
import re

def lint_code_against_guardrails(file_content, file_type):
    violations = []
    
    # 检查移动端 target blank
    if file_type in ["html", "jsx", "tsx", "vue"]:
        if re.search(r'target=["\']_blank["\']', file_content) and not re.search(r'rel=["\'].*?noopener.*?["\']', file_content):
            violations.append("[军规拦截 1.1] 发现 target='_blank' 缺失 rel='noopener noreferrer'，存在严重钓鱼劫持与移动端性能泄露风险！")
            
    # 检查 Python requests 裸奔
    if file_type == "py":
        if re.search(r'requests\.(get|post|put)\(', file_content) and not re.search(r'headers\s*=', file_content):
            violations.append("[军规拦截 2.1] 发起 HTTP 请求未显式传入自定义 headers，极易触发 CDN/Cloudflare 403 阻断拦截！")
            
    # 检查 Windows 编码
    if file_type in ["bat", "cmd"]:
        if "chcp 65001" not in file_content:
            violations.append("[军规拦截 3.1] Windows 批处理脚本未在首行设置 chcp 65001，存在中文输出乱码隐患！")
            
    return violations

if __name__ == '__main__':
    sample_html = '<a href="https://partner.com" target="_blank">点击赞助</a>'
    issues = lint_code_against_guardrails(sample_html, "html")
    for issue in issues:
        print(issue)
```

## 风险与边界
- 军规库应聚焦于“具有通用确定性危害的硬伤”，避免将主观的代码风格偏好（如缩进 2 空格还是 4 空格）混入军规库导致规则臃肿。
- 当上游第三方库架构出现破坏性升级（Breaking Change）时，应及时在复盘中更新对应规则。

## 使用建议
- 建立“三次犯错即入库”机制：只要同一个环境或配置问题在团队中出现 2 次以上，立即提炼成一条具象的防御代码注入军规库。
- 在每次重大版本交付或自动化部署（CI/CD）前，前置挂载 Linter 脚本进行阻塞式自检。

## 成功标准
- 彻底消灭已入库的历史重复性 Bug。
- 自动化代码生成 100% 通过军规自检。
- 形成可持续自我进化的团队工程记忆中枢。

## 源文件
来源：awesome-openclaw-zh  
原始文件：engineering-memory-guardrails.md