🚀 快速开始
环境要求
必需
- ✓ Linux 系统（国产系统优先）
- ✓ Claude Code CLI 已安装
- ✓ 管理员权限（sudo/root）
- ✓ 网络连接（初次使用）
推荐
- ✓ 国产系统：deepin 23+, UOS, Kylin
- ✓ 或 Debian 11+, Ubuntu 20.04+
- ✓ 5GB 可用磁盘空间
- ✓ 基础命令行知识
3 分钟上手
步骤 1: 克隆项目
git clone https://github.com/shaoqing404/ops_spec_kylin.git
cd ops_spec_kylin步骤 2: 启动 Claude Code
# 在项目根目录启动
claude-code步骤 3: 执行第一个命令
# 在 Claude Code 中执行
/ops.detect这将检测你的系统信息并生成 JSON 报告
🎉 完成！如果看到系统信息输出，说明环境已就绪。
📖 命令参考
Project Sentinel 提供 9 个核心 ops 命令，覆盖系统初始化到安全扫描的全流程。
/ops.init
初始化项目目录结构并记录系统快照
功能
- 创建 scripts/, configs/, logs/, docs/ 目录
- 记录系统快照到 logs/sysinfo.json
- 幂等执行，支持重复运行
使用方式
/ops.init [--config-only] [--force]参数说明
| --config-only | 仅创建配置目录 |
| --force | 强制重新初始化 |
产物
scripts/- 可执行脚本目录logs/sysinfo.json- 系统信息快照
/ops.detect
检测系统发行版、包管理器和镜像源连通性
功能
- 识别发行版类型和版本（deepin/UOS/Kylin/Ubuntu/RHEL）
- 检测包管理器（apt/dnf/zypper）
- 测试 TUNA/USTC 镜像连通性
- 输出 JSON 格式系统报告
使用方式
/ops.detect [--format=json|text] [--timeout=3] [--no-test]输出示例
{
"distribution": "deepin",
"version": "23",
"architecture": "x86_64",
"package_manager": "apt",
"mirrors": {
"tuna": {"reachable": true, "responseMs": 150},
"ustc": {"reachable": true, "responseMs": 200}
}
}/ops.mirrors
测试、切换和恢复软件镜像源
功能
- 测试镜像源可用性（TUNA/USTC/阿里云）
- 安全切换软件源（自动备份）
- 回滚到之前的配置
使用方式
/ops.mirrors --action=test|switch|restore [--profile=tuna|ustc] [--dry-run]示例场景
# 测试所有镜像源
/ops.mirrors --action=test
# 切换到 TUNA 镜像
/ops.mirrors --action=switch --profile=tuna
# 回滚到备份配置
/ops.mirrors --action=restore⚠️ 安全保障：切换前自动备份到 configs/backup/，失败自动回滚
/ops.conda
安装 Miniconda 并配置国内 pip/conda 镜像
功能
- 自动安装 Miniconda（清华镜像下载）
- 配置 pip 和 conda 国内镜像源
- 验证 Python 环境正常
使用方式
/ops.conda [--action=install|check|update] [--mirror=tuna|ustc] [--yes]产物
- Miniconda:
/opt/miniconda3/ - pip 配置:
~/.pip/pip.conf - conda 配置:
~/.condarc
/ops.toolchain
安装 C/C++ 开发工具链（自动适配包管理器）
功能
- Debian/Ubuntu: build-essential, cmake, gdb
- RHEL/CentOS: "Development Tools" 组, cmake, gdb
- SUSE: patterns-devel-base-devel_basis
使用方式
/ops.toolchain [--lang=c|cpp|both] [--with=make,cmake,gdb] [--verify]/ops.monitor
安装系统监控工具（htop, iotop, nethogs）
支持的工具
| htop | 交互式进程查看器 |
| iotop | 磁盘 I/O 监控 |
| nethogs | 网络流量监控 |
使用方式
/ops.monitor [--tools=htop,iotop] [--install-all] [--generate-guide]/ops.sec.clamav
安装和使用 ClamAV 病毒扫描工具
功能
- 安装 ClamAV 和病毒库
- 更新病毒定义（freshclam）
- 扫描指定目录或快速扫描
使用方式
/ops.sec.clamav --action=install|update|scan [--path=/home] [--quick]✓ 默认仅报告不删除，使用 --quarantine 启用隔离
/ops.proc.kill
安全终止进程（支持二次确认）
功能
- 按进程名、PID 或端口查找并终止
- 显示进程详情并二次确认
- 支持多种信号（TERM/KILL/HUP）
使用方式
/ops.proc.kill [--name=] [--pid=] [--port=] [--signal=TERM] 示例
# 终止占用 8080 端口的进程
/ops.proc.kill --port=8080
# 强制终止进程（跳过确认）
/ops.proc.kill --pid=12345 --signal=KILL --force/ops.docs.sync
自动生成运维手册（汇总所有脚本用法）
功能
- 扫描 scripts/ 目录下所有脚本
- 提取注释和用法说明
- 生成统一的 ops-cookbook.md
使用方式
/ops.docs.sync [--format=markdown|html] [--incremental]产物
docs/ops-cookbook.md - 完整运维手册
💡 实战案例
案例 1: 新系统完整初始化（10分钟）
适用场景：全新安装的国产 Linux 系统，需要配置完整开发环境
# 步骤 1: 初始化项目
/ops.init
# 步骤 2: 检测系统
/ops.detect
# 步骤 3: 切换到国内镜像
/ops.mirrors --action=switch --profile=tuna
# 步骤 4: 安装 Python 环境
/ops.conda --action=install --yes
# 步骤 5: 安装 C/C++ 工具链
/ops.toolchain --lang=both --verify
# 步骤 6: 安装监控工具
/ops.monitor --install-all✓ 预期耗时: 8-10 分钟 | 状态: 生产就绪
案例 2: 仅切换镜像源（2分钟）
适用场景：现有系统软件源速度慢，需要切换到国内镜像
# 测试所有镜像源速度
/ops.mirrors --action=test
# 切换到响应最快的镜像（如 USTC）
/ops.mirrors --action=switch --profile=ustc
# 如果切换后有问题，立即回滚
/ops.mirrors --action=restore案例 3: Python 开发环境配置
适用场景：数据科学/Python 开发，需要 Conda 和国内镜像
# 安装 Miniconda
/ops.conda --action=install --mirror=tuna --yes
# 验证安装
/ops.conda --action=check
# 测试 pip 和 conda
conda -V
pip --version案例 4: 系统安全扫描
适用场景：定期安全检查，扫描下载目录和临时文件
# 安装 ClamAV
/ops.sec.clamav --action=install
# 更新病毒库
/ops.sec.clamav --action=update
# 快速扫描（仅扫描 Downloads 和 /tmp）
/ops.sec.clamav --action=scan --quick
# 完整扫描 /home 目录
/ops.sec.clamav --action=scan --path=/home案例 5: 故障诊断与进程管理
适用场景：端口被占用，需要查找并终止僵尸进程
# 查找占用 8080 端口的进程（dry-run）
/ops.proc.kill --port=8080 --dry-run
# 确认后终止
/ops.proc.kill --port=8080
# 终止所有 nginx 进程
/ops.proc.kill --name=nginx🔧 如何定制你的哨兵：功能扩展指南
基于 Project Sentinel 框架扩展新功能，打造属于自己的运维助手
📋 前置准备：配置 Kat-coder API
Project Sentinel 由 Kat-coder 驱动，这是一个强大的 32B 代码生成模型。
步骤 1: 申请 Kat-coder API
访问 快手流云平台 申请 API 密钥
步骤 2: 配置 Claude Code 环境变量
# 方式1: 通过环境变量（推荐）
export ANTHROPIC_API_KEY="your-kat-coder-api-key"
# 方式2: 通过 Claude Code 配置
claude config set api_key your-kat-coder-api-key步骤 3: 验证配置
cd ops_spec_kylin
claude✓ 如果看到 "🛡️ Project Sentinel 已就绪"，说明配置成功！
🔄 spec-kit 完整工作流：从需求到实现
Project Sentinel 基于 spec-kit 框架，采用规范驱动开发 (Specification-Driven Development) 理念。
步骤 0: 告知 AI 准备扩展新功能
用自然语言告诉 AI：
"我准备为 Project Sentinel 扩展一个新功能，请先阅读 AI-GUIDE.md 文件"AI 会自动了解项目架构、安全原则和开发规范
步骤 1: /speckit.specify — 描述需求与边界
用自然语言描述你想要的功能，只说做什么，不说怎么做。
/speckit.specify示例：添加磁盘清理功能
## 功能目标
为 Project Sentinel 添加磁盘清理功能，帮助用户安全清理系统垃圾文件。
## 核心需求
- 检测并显示可清理的文件（包管理器缓存、临时文件、日志文件）
- 支持 --dry-run 模式预览清理内容
- 清理前必须用户确认，防止误删
- 支持 apt/dnf/zypper 等不同包管理器💡 新手提示：不确定技术边界？在这步简单描述需求，后续让 AI 帮你完善
步骤 2: /speckit.plan — 构建技术路线与适配矩阵
让 AI 设计技术实现方案和跨系统适配策略。
/speckit.plan如果你是技术新手，可以这样引导 AI：
"我不太确定技术实现细节，请根据我的需求帮我设计技术路线和适配方案"AI 会生成适配矩阵和关键脚本清单
步骤 3: /speckit.tasks — 任务拆解 + 验收标准
将计划拆解成具体的可执行任务。
/speckit.tasksAI 会生成 tasks.md，包含：
- 任务列表（T1, T2, T3...）
- 产物路径（scripts/*.sh）
- 验收标准
- 回滚策略
步骤 4: /speckit.analyze — 保持概述文件统一
确保 spec.md、plan.md、tasks.md 三份文件内容一致，没有冲突。
/speckit.analyze⚠️ 重要：如果发现问题，可能需要多次运行并根据建议修改文档，直到检查全部通过
步骤 5: /speckit.implement — 执行实现 🚀
一切准备就绪后，让 AI 自动生成代码和文档。
/speckit.implement⚡ Kat-coder 的强大之处
在实现阶段，你甚至不需要手动执行命令！只需：
- 按下
Shift + Tab启用 Claude Code 的自动运行模式 - AI 会自动按照 tasks.md 中的任务顺序依次生成代码、运行测试、更新文档
- 整个过程完全自动化，你只需观察进度和结果
⚡ 示例：15 分钟添加"系统备份"功能
# 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，然后重新运行直到通过。这个步骤很重要，确保需求、设计、任务三者一致。
💡 新手友好提示
-
▸
不确定技术方案？
在 /speckit.plan 阶段直接问 AI -
▸
不知道如何拆解任务？
在 /speckit.tasks 阶段让 AI 主导 -
▸
担心代码质量？
信任框架的安全机制和质量门禁
⚡ 高效扩展秘诀
-
✓
批量扩展：
可以在一个 spec.md 中描述多个相关功能 -
✓
迭代优化：
功能上线后，再次运行 /speckit.specify 描述改进需求 -
✓
复用模板：
参考 .specify/templates/ 中的模板文件
🔧 故障排查
问题: 命令执行提示权限不足
错误信息: Permission denied
解决方案:
大部分 ops 命令需要管理员权限。使用 sudo 重新启动 Claude Code：
sudo claude-code
问题: 镜像源切换后无法更新包
错误信息: Failed to fetch
解决方案:
- 使用
/ops.mirrors --action=restore回滚到备份 - 检查网络连接：
ping mirrors.tuna.tsinghua.edu.cn - 尝试其他镜像源：
/ops.mirrors --action=switch --profile=ustc
问题: Conda 安装后找不到命令
错误信息: conda: command not found
解决方案:
需要重新加载环境变量或重启终端：
source ~/.bashrc # 或 exec bash
问题: 磁盘空间不足
错误信息: No space left on device
解决方案:
- 检查磁盘使用情况：
df -h - 清理 apt 缓存：
sudo apt clean - 清理 conda 缓存：
conda clean --all
📊 项目状态
完成度：100%
所有 11 个阶段（Phase 1-11）已全部完成 ✅
✅ 已完成功能
- ✓ 系统检测与发行版识别
- ✓ 镜像源管理（TUNA/USTC）
- ✓ Python/Conda 环境配置
- ✓ C/C++ 工具链安装
- ✓ 监控与安全工具
- ✓ 进程管理与诊断
- ✓ 文档自动生成
- ✓ 离线模式支持
- ✓ 专家/安全模式
- ✓ 质量门禁（shellcheck/bats）
- ✓ 安全审计框架
📦 核心交付物
48个 Shell 脚本68个测试文件9个 ops 命令8个 speckit 命令- 完整 constitution.md
- 详细 AI-GUIDE.md
- 质量门禁配置
- 安全审计日志