DebianClub AI Skills

DebianClub AI Skills 是一组给 AI 编码助手和终端代理使用的 Debian/Linux 可靠性规则。它们的目标不是替代文档，而是让 AI 在回答之前先识别环境、验证包名、检查日志和评估命令风险。

当前仓库内的首个 skill 是 skills/debian-linux-reliability/。它采用一个主 skill、多模块子功能的结构。

为什么需要

Linux 上的 AI 幻觉通常来自几个地方：

• 把 Ubuntu、Arch、macOS 的命令套到 Debian 上
• 编造不存在的软件包名
• 忽略 Debian stable、backports、testing 的差异
• 没看 systemctl 和 journalctl 就猜服务失败原因
• 推荐 curl | sh、rm -rf、chmod -R 等高风险命令
• 没识别 WSL、容器、无 systemd 环境或非 amd64 架构

DebianClub AI Skills 要求 AI 先收集这些事实，再给出建议。

当前 Skill

子功能

debian-linux-reliability 包含这些模块：

安全策略

第一版默认禁止自动修改系统。脚本只收集信息，不安装软件、不删除文件、不编辑配置、不重启服务。

如果用户希望 AI 执行修改，AI 必须先说明：

• 会影响哪些文件、包、服务或网络规则
• 为什么需要修改
• 修改前如何检查
• 修改后如何验证
• 失败时如何回滚

与 DebianClub 文档的关系

这个 skill 会优先引用 DebianClub 仓库里的文档作为解释来源，例如：

• APT 包管理
• Debian Backports
• deb822 软件源
• 网络配置
• NVIDIA Optimus
• Podman
• 系统安全

但实时状态必须以用户机器上的检查结果为准。文档负责解释，脚本负责验证当前系统事实。

使用方式

在支持 skills 的 AI agent 中，可以显式要求：

Use $debian-linux-reliability to diagnose this Debian package installation issue.

如果只是阅读仓库，可以查看：

skills/debian-linux-reliability/SKILL.md
skills/debian-linux-reliability/references/
skills/debian-linux-reliability/scripts/

本地安装

仓库提供了一个用户目录安装脚本，默认安装到 ${CODEX_HOME:-$HOME/.codex}/skills。它不会使用 sudo，也不会覆盖已有安装，除非显式传入 --replace。

bash skills/scripts/install-skill.sh debian-linux-reliability

如果目标目录已有同名 skill，先检查现有内容；确认要替换时再运行：

bash skills/scripts/install-skill.sh --replace debian-linux-reliability

平台或 CLI 可以读取分发索引：

skills/registry.json
/skills.json

发布与评估

构建版本化 skill 包：

bash skills/scripts/package-skill.sh debian-linux-reliability

脚本会生成 .tgz 包和对应 manifest，包含版本号、大小和 SHA-256。默认输出目录是 skills/dist/，该目录不纳入版本库。

发布到远端 GitHub Release：

bash skills/scripts/publish-skill-release.sh --dry-run debian-linux-reliability
version="$(jq -r '.skills[] | select(.name == "debian-linux-reliability") | .version' skills/registry.json)"
git tag "skills/debian-linux-reliability/v${version}"
git push origin "skills/debian-linux-reliability/v${version}"

--dry-run 只构建和打印发布命令，不上传。推送 tag 后，.github/workflows/skills-release.yml 会重新验证、打包并上传 .tgz 与 manifest。

对真实 agent 回答生成评分报告：

bash skills/scripts/score-evaluation.sh --responses path/to/responses --output report.md

评分报告会同时输出 excellent、pass、risky、fail 四档等级。对于只包含部分 prompt 的失败样本或回归样本，可以使用：

bash skills/scripts/score-evaluation.sh --responses path/to/responses --present-only

如果是真实使用中沉淀的新 prompt 集，可以指定自定义 prompt 文件：

bash skills/scripts/score-evaluation.sh --prompts path/to/prompts.md --responses path/to/responses

长期维护流程：

• 先脱敏真实问题和回答，移除主机名、用户名、IP、token、私钥和客户标识
• 将新 prompt 加到 tests/field-regression-prompts.md，或按主题新增 prompt 文件
• 将对应 agent 回答放入独立 responses 目录
• 在 tests/regression-cases.tsv 登记 prompt 文件、responses 目录、期望等级和样本数
• 运行 bash skills/scripts/validate-all.sh，确认登记的 prompt 文件编号、coverage、模块名以及正向、负向、边界和真实回归样本都通过

维护资源

当前已包含：

• 多语言说明：简体中文、繁体中文、日文、韩文
• 真实排障样例：tests/evaluation-prompts.md 中覆盖 APT、systemd、网络、GPU、容器、开发环境、Debian 打包和安全审计场景
• 真实 agent 回答基线：tests/fixtures/evaluation-responses/ 中包含 30 条可评分样本
• 失败回答样本：tests/fixtures/failure-responses/ 中包含危险命令、跨发行版源和未审批修改等负向样本
• 边界语境样本：tests/fixtures/edge-responses/ 覆盖“正确警告”和“带安全词但仍建议执行危险命令”的评分边界
• 真实回归种子：tests/field-regression-prompts.md 和 tests/fixtures/field-regression-responses/ 提供长期入库格式
• 回归样本清单：tests/regression-cases.tsv 会把正向基线和负向样本纳入持续验证
• 自动化验证：skills/scripts/validate-all.sh 会校验 skill 元数据、分发索引、脚本语法、风险检查、脱敏规则和排障样例覆盖
• 本地分发入口：skills/registry.json 和 skills/scripts/install-skill.sh
• 版本化发布：skills/scripts/package-skill.sh
• 远端发布：skills/scripts/publish-skill-release.sh 和 .github/workflows/skills-release.yml
• agent 分级评分报告：skills/scripts/score-evaluation.sh

后续计划

后续会继续从真实使用中补充更多回归样本。