AI驱动的国产Linux系统运维助手
让Linux系统听懂你的意图与边界 · 本项目基于Claude Code与spec-kit的规范驱动开发
"哨兵"不是要取代人，而是要让人重新掌握那份熟悉感。
在国产Linux系统环境中，每一次软件源切换、每一次配置修改，都像是在盲飞。工具在变，命令在变，甚至标准也在变——唯一没变的，是那种"怕出错"的紧张感。
Project Sentinel 的使命，是做第一盏航标：
- 把命令记忆换成意图表达与边界设定：你只要说想做什么，剩下的交给我。
- 把一次性操作换成可回滚的掌控感：后悔药是吗？我按斤卖。
- 让复杂的系统操作变得可理解、可回滚、可验证：解开迷雾的面纱，让系统回归本位，让操作不再复杂。
借助 Kat-Coder 和 Claude Code，我们相信 AI 不是做事的机器，而是让人重新理解系统的中介。
- ✅ 意图驱动：用自然语言描述需求，AI自动生成安全代码
- ✅ 安全第一：默认
--dry-run，所有危险操作必须显式确认 - ✅ 可回滚性：改源前自动备份，失败自动回滚
- ✅ 幂等执行：重复运行无副作用，日志全程记录
- ✅ 离线优先：支持国内镜像源（TUNA/USTC），离线降级策略
Project Sentinel 是一个由 Kat-Coder 驱动并运行在 Claude Code 环境中的 AI编程框架，类似 spec-kit，致力于国产操作系统用户带来贾维斯一样的流畅系统控制体验。
graph TB
A[最终用户<br/>初次接触国产系统/<br/>0编程经验新手] -->|自然语言指令| B[AI编程工具<br/>Kat-coder for Claude Code]
B -->|读取并遵循| C[Project Sentinel<br/>AI运维框架]
C -->|实时生成| D[运维脚本<br/>scripts/*.sh]
D -->|执行于| E[用户的Linux系统<br/>deepin/UOS/Kylin]
| 概念 | 说明 | 归属 |
|---|---|---|
| Claude Code | AI编程工具（开发环境） | 外部工具，用户安装 |
| spec-kit | 开发方法论（类似敏捷） | 外部框架，我们参考 |
| Project Sentinel | AI运维框架（本项目） | 我们开发的核心 |
| scripts/*.sh | Bash脚本 | AI生成的产物 |
| Kat-coder | 快手开发的编程模型 | 驱动项目的AI引擎 |
|
用户可以直接用自然语言下达指令（如"帮我安装C++编译工具"），AI会自动分析、规划并安全执行 |
重点支持统信UOS、深度Deepin、银河麒麟等，内置对这些系统特有配置和包管理器的适配 |
提供一套预定义的、经过验证的自动化脚本，覆盖环境初始化、软件安装、系统监控、安全扫描等全流程 |
- ✅ Linux系统（deepin/UOS/Kylin/Ubuntu/Debian）
- ✅ Claude Code CLI 已安装
- ✅ 管理员权限（sudo）
- ✅ 网络连接（初次使用）
- ✅ 申请 Kat-coder API 并完成配置
# 1. 克隆项目
git clone https://github.com/shaoqing404/ops_spec_kylin.git
cd ops_spec_kylin
# 2. 启动 Claude Code（项目会自动识别）
claude
# 3. 在 Claude Code 中执行第一个命令
/ops.init🎉 完成！ 初始化后会显示精美的欢迎信息和快速开始指南。
提示：
- Claude Code 启动时会自动识别 Project Sentinel 并问候你
- 运行
/sentinel随时查看系统状态和快速命令指南 - 第二次启动时，框架会自动加载，无需重新初始化
适用于全新安装的国产Linux系统，一键配置完整开发环境：
# 在 Claude Code 中依次执行：
/ops.init # 初始化项目结构
/ops.detect # 检测系统信息
/ops.mirrors --action=switch --profile=tuna # 切换国内镜像
/ops.conda --action=install --yes # 安装Python环境
/ops.toolchain --lang=both --verify # 安装C/C++工具链
/ops.monitor --install-all # 安装监控工具我们不只是在"使用"AI，而是利用 spec-kit 框架来"驾驭"AI：
-
宪法式AI (Constitutional AI) 通过
constitution.md定义不可违背的安全和风格准则（如：操作必须幂等、禁止硬编码密钥） -
三步航线
- 💭 意图 (
/speckit.specify) — 用自然语言描述需求 - 🛡️ 约束 (
/speckit.plan) — 提供技术约束和安全边界 - ↩️ 回滚点 (
/speckit.tasks) — AI分解任务并逐一执行
- 💭 意图 (
-
证据驱动执行 任何危险动作都在
--dry-run模式先呈现证据，再由用户确认执行
我们帮助用户从"被系统牵着走"提升到"扩展系统边界"：
Level 0: 被系统牵着走
Level 1: 能走既定路线
Level 2: 看懂系统脉络 ← AI压缩这段学习疼痛带
Level 3: 可做选择与取舍
Level 4: 扩展系统边界
在国产化替代进程中，员工对新系统的熟练度是主要挑战。利用 32B-Coder 级模型驱动AI助手，让员工通过自然语言操控系统，实现平稳过渡。
借助大模型的开放能力，引导用户走过"了解系统 → 应用系统 → 操作系统 → 控制系统"的完整路径。最终用户将能通过 Python/R/C++ 等工具构建自己的独立应用。
- ✅ 新系统完整初始化（10分钟）
- ✅ 仅切换镜像源（2分钟）
- ✅ Python开发环境配置
- ✅ 系统安全扫描
- ✅ 故障诊断与进程管理
详细案例请查看：用户指南 (HTML) 或 docs/offline-guide.md
| 文档 | 说明 | 适合人群 |
|---|---|---|
| AI-GUIDE.md | AI代理必读：项目架构、工作流程、命令参考 | AI / 开发者 |
| docs/constitution.md | 项目宪法：安全原则、质量门槛、风险规则 | AI |
| docs/offline-guide.md | 离线/内网环境使用指南 | 企业用户 |
| docs/quality-gate.md | 质量门禁：shellcheck/bats测试规范 | 开发者 |
| docs/index.html | 项目主页（精美HTML版） | 通用 |
| docs/user-guide.html | 使用指南（精美HTML版） | 新手 |
ops_spec_kylin/
├── scripts/ # 48个Shell脚本（AI生成的运维工具）
├── configs/ # 配置文件与备份
├── tests/ # 68个bats测试用例
├── docs/ # 完整文档（宪法/指南/架构分析/HTML页面）
├── specs/ # 需求规范与任务拆解
├── logs/ # 运行时日志（不纳入版本控制）
├── AI-GUIDE.md # AI代理指南（重要！）
└── README.md # 本文件
Project Sentinel 提供 1个快捷命令 + 9个核心ops命令，覆盖系统初始化到安全扫描的全流程：
| 命令 | 功能 | 说明 |
|---|---|---|
/sentinel |
系统状态仪表盘 | 显示项目状态、快速命令指南和系统健康检查 |
| 命令 | 功能 | 示例 |
|---|---|---|
/ops.init |
初始化项目结构 | /ops.init |
/ops.detect |
检测系统信息 | /ops.detect --format=json |
/ops.mirrors |
镜像源管理 | /ops.mirrors --action=switch --profile=tuna |
/ops.conda |
Python环境配置 | /ops.conda --action=install --yes |
/ops.toolchain |
C/C++工具链安装 | /ops.toolchain --lang=both |
/ops.monitor |
系统监控工具 | /ops.monitor --install-all |
/ops.sec.clamav |
病毒扫描 | /ops.sec.clamav --action=scan --quick |
/ops.proc.kill |
进程管理 | /ops.proc.kill --port=8080 |
/ops.docs.sync |
文档自动生成 | /ops.docs.sync |
详细参数说明请查看：用户指南
所有 11 个阶段（Phase 1-11）已全部完成，包括：
- Phase 1-2: 项目初始化与系统检测
- Phase 3-4: 镜像源管理与Python环境
- Phase 5-6: 工具链安装与监控工具
- Phase 7-8: 安全扫描与进程管理
- Phase 9: 离线模式支持
- Phase 10: 专家/安全模式切换
- Phase 11: 安全审计框架与宪法合规性
- 📦 48个 Shell脚本
- 🧪 68个 bats测试文件
- 📝 9个 ops命令
- 📚 8个 speckit命令
- 🛡️ 完整的 constitution.md
- 📖 详细的 AI-GUIDE.md
- ✅ 质量门禁配置（shellcheck/bats）
- 🔒 安全审计日志
不是围栏困住AI，而是通过"宪法"（constitution.md）塑造AI的判断力：
- 意图 → 证据 → 执行 → 回滚，路径全程可审计
- 16类风险行为知识库，AI强制阅读并综合判断
- 默认
--dry-run，用户明确批准才执行
基于概率论的双模型协作安全机制：
-
$M_1$ （小模型）初步筛查风险代码块 -
$M_2$ （大模型）阅读风险描述并综合判断 - 混合策略确保100%召回率（$E_3 = 1$）
详见：项目主页#安全设计
每个脚本自动生成文档片段，通过 /ops.docs.sync 汇总到 docs/ops-cookbook.md，确保文档与代码同步。
- ✅ 最小权限：默认使用官方/可信镜像，GPG校验
- ✅ 备份优先：改源前必须备份到
configs/backup/<timestamp>/ - ✅ 幂等执行：脚本可重复运行，二次执行无副作用
- ✅ 可观测性：关键步骤输出日志到
logs/，错误统一出口 - ✅ 干跑模式：所有危险操作支持
--dry-run
# 示例：安全切换镜像源
/ops.mirrors --action=test # 1. 先测试所有镜像可用性
/ops.mirrors --action=switch --dry-run # 2. 干跑模式预览变更
/ops.mirrors --action=switch # 3. 执行（自动备份）
/ops.mirrors --action=restore # 4. 失败时回滚本项目已参与 Kat-coder AI 挑战赛。
- 开源协议：BSD-2-Clause License
- 当开源协议与赛事条款出现冲突时，请以赛事条款为准（"排除此赛事"）
- 日后若在其他项目中复用代码，请再次确认遵循相应的开源许可
- 📧 邮件：zhengchi.cntv@gmail.com
- 🐛 Issues：GitHub Issues
- 📚 详细日志：查看
logs/*.log
- Claude Code - AI编程环境
- spec-kit - 规范驱动开发框架
- Kat-Coder - 32B代码生成模型
- bats-core - Bash测试框架
🎯 本节教你如何基于 Project Sentinel 框架扩展新功能，打造属于自己的运维助手
Project Sentinel 由 Kat-coder 驱动，这是一个强大的 32B 代码生成模型。在开始扩展前，你需要：
访问 快手流云平台 申请 Kat-coder API 密钥。
在 Claude Code 中设置 API 密钥：
# 方式1: 通过环境变量（推荐）
export ANTHROPIC_API_KEY="your-kat-coder-api-key"
# 方式2: 通过 Claude Code 配置
claude config set api_key your-kat-coder-api-key启动 Claude Code 并进入项目目录：
cd ops_spec_kylin
claude如果看到 "🛡️ Project Sentinel 已就绪"，说明配置成功！
Project Sentinel 基于 spec-kit 框架，采用规范驱动开发 (Specification-Driven Development) 理念。以下是完整的功能扩展流程：
# 在 Claude Code 中，用自然语言告诉 AI：
"我准备为 Project Sentinel 扩展一个新功能，请先阅读 AI-GUIDE.md 文件"AI 会自动读取 AI-GUIDE.md 并了解项目架构、安全原则和开发规范。
用自然语言描述你想要的功能，只说做什么，不说怎么做。
示例：添加磁盘清理功能
/speckit.specify在弹出的编辑器中输入：
## 功能目标
为 Project Sentinel 添加磁盘清理功能，帮助用户安全清理系统垃圾文件。
## 核心需求
- 检测并显示可清理的文件（包管理器缓存、临时文件、日志文件）
- 支持 --dry-run 模式预览清理内容
- 清理前必须用户确认，防止误删
- 支持 apt/dnf/zypper 等不同包管理器
## 边界条件
- 仅清理系统缓存和临时文件，不触碰用户数据
- 不清理 /home 目录下的文件
- 清理前必须备份清理列表到 logs/
## 非目标
- 不进行深度磁盘碎片整理
- 不清理第三方应用缓存提示：如果你是新手，不确定技术边界，可以在这步简单描述需求，后续让 AI 帮你完善。
让 AI 设计技术实现方案和跨系统适配策略。
/speckit.plan如果你是技术新手，可以这样引导 AI：
"我不太确定技术实现细节，请根据我的需求帮我设计技术路线和适配方案"
AI 会生成类似这样的 plan.md：
## 技术路线
- Shell 脚本实现，调用系统包管理器工具
- 检测逻辑：使用 du -sh 统计缓存大小
- 清理逻辑：根据包管理器类型调用对应清理命令
## 适配矩阵
| 发行版 | 包管理器 | 缓存路径 | 清理命令 |
|--------|---------|---------|---------|
| deepin/UOS | apt | /var/cache/apt | apt-get clean |
| Kylin | dnf | /var/cache/dnf | dnf clean all |
| NeoKylin | yum | /var/cache/yum | yum clean all |
## 关键脚本
- scripts/disk_cleanup.sh - 主清理脚本
- scripts/disk_check.sh - 磁盘空间检查将计划拆解成具体的可执行任务。
/speckit.tasksAI 会生成 tasks.md：
## 任务列表
### T1: 发行版与包管理器检测
- **产物**: scripts/detect_pkg_manager.sh
- **验收**: 正确识别 apt/dnf/yum/zypper
- **回滚**: 无需回滚
### T2: 缓存空间统计
- **产物**: scripts/disk_check.sh
- **验收**: 输出各缓存目录大小，支持 --json
- **回滚**: 无需回滚
### T3: 磁盘清理脚本
- **产物**: scripts/disk_cleanup.sh
- **验收**:
- 支持 --dry-run 预览
- 清理前备份列表到 logs/cleanup_<timestamp>.log
- 清理后显示释放空间
- **回滚**: 无法恢复已删除缓存（设计为安全操作）
### T4: 文档更新
- **产物**: docs/ops-cookbook.md 更新
- **验收**: 文档包含命令示例和参数说明确保 spec.md、plan.md、tasks.md 三份文件内容一致，没有冲突。
/speckit.analyzeAI 会进行交叉检查：
✅ 检查通过：spec 中的需求在 tasks 中都有对应任务
✅ 检查通过：plan 中的技术路线与 tasks 一致
⚠️ 发现问题：spec 中提到"备份清理列表"，但 plan 中未体现
建议：在 plan.md 的"关键设计"章节补充备份策略
重要：如果发现问题，可能需要多次运行 /speckit.analyze 并根据建议修改文档，直到检查全部通过。
一切准备就绪后，让 AI 自动生成代码和文档。
/speckit.implementKat-coder 的强大之处：
在实现阶段，你甚至不需要手动执行命令！只需：
- 按下
Shift + Tab启用 Claude Code 的自动运行模式 - AI 会自动按照
tasks.md中的任务顺序依次生成代码、运行测试、更新文档 - 整个过程完全自动化，你只需观察进度和结果
实现过程示例：
[Task 1/4] 生成 scripts/detect_pkg_manager.sh...
✅ 脚本已生成
✅ shellcheck 检查通过
✅ 测试用例通过
[Task 2/4] 生成 scripts/disk_check.sh...
✅ 脚本已生成
✅ 幂等性验证通过
[Task 3/4] 生成 scripts/disk_cleanup.sh...
✅ 脚本已生成
✅ --dry-run 模式验证通过
✅ 备份机制验证通过
[Task 4/4] 更新文档...
✅ docs/ops-cookbook.md 已更新
🎉 实现完成！已生成 3 个脚本，更新 1 份文档。
-
不确定技术方案？ 在
/speckit.plan阶段直接问 AI："我不了解 Linux 包管理器，请帮我设计跨发行版的兼容方案" -
不知道如何拆解任务？ 在
/speckit.tasks阶段让 AI 主导："根据 plan.md 自动生成任务列表，包含验收标准和产物路径" -
担心代码质量？ 信任框架的安全机制：
- 所有代码自动通过 shellcheck 检查
- 危险操作强制 --dry-run
- constitution.md 确保 AI 遵循安全原则
- 批量扩展：可以在一个 spec.md 中描述多个相关功能，一次性实现
- 迭代优化：功能上线后，可以再次运行
/speckit.specify描述改进需求 - 复用模板：参考
.specify/templates/中的模板文件，快速起草新需求
# 1. 告知 AI
"准备扩展系统备份功能，请阅读 AI-GUIDE.md"
# 2. 描述需求
/speckit.specify
# 输入：支持备份 /etc 和用户指定目录，压缩为 tar.gz，存储到 configs/backup/
# 3. 设计方案
/speckit.plan
# AI 自动生成：备份策略、压缩算法、存储路径规划
# 4. 拆解任务
/speckit.tasks
# AI 生成：T1 备份脚本、T2 恢复脚本、T3 定时任务配置
# 5. 一致性检查
/speckit.analyze
# 修复发现的问题（如有）
# 6. 自动实现
/speckit.implement
# 按 Shift+Tab，坐等完成 ☕Q: 我没有编程经验，能用这个框架吗？ A: 完全可以！只需用自然语言描述需求，AI 会处理所有技术细节。
Q: 如果 AI 生成的代码有问题怎么办？ A: 框架内置质量门禁（shellcheck、bats 测试），有问题会自动拦截并提示修复。
Q: 可以扩展非运维功能吗（如写 Python 小工具）？ A: 可以！框架支持生成 C/Python/Shell 等多种语言的工具，只需在 spec 中说明即可。
Q: /speckit.analyze 报错怎么办？
A: 按照 AI 的建议修改 spec.md 或 plan.md，然后重新运行直到通过。这个步骤很重要，确保需求、设计、任务三者一致。
为什么 Shift+Tab 就能完成一切？
Kat-coder 是一个 32B 参数的代码生成模型，专门训练用于：
- 理解自然语言需求并生成高质量代码
- 遵循 constitution.md 中的安全和质量约束
- 自动补全任务、运行测试、更新文档
当你按下 Shift+Tab 启用自动模式后：
- AI 读取
tasks.md中的任务列表 - 按顺序生成每个任务的代码产物
- 自动运行 shellcheck/bats 验证
- 更新
docs/ops-cookbook.md文档 - 记录操作日志到
logs/
这就是"规范驱动开发"的威力：你只需定义做什么（spec），AI 负责怎么做（implement）。
