chquandogong/Quipu

# Quipu

面向团队的 Linux 工作站健康调查平台
它不是系统监视器，而是将问题排查过程产品化的本地优先调查工具。

한국어 | English | 简体中文

## 概览 Quipu 将多台 Linux 笔记本和开发工作站上出现的 过热、重启、图形会话错误、存储设备警告、Wi-Fi 不稳定以及物理 环境变化集中到一处，帮助团队共同进行调查。 核心不在于展示大量图表，而在于快速回答以下问题： - 目前应该优先查看哪台设备？ - 为什么存在风险？ - 最可能的原因是什么？ - 有哪些支持证据和反对证据？ - 人员接下来应该检查或采取什么行动？ - 采取措施后，状态是否真的有所改善？ - 同样的问题是否在其他设备上重复出现？ ``` Detect -> Triage -> Investigate -> Hypothesize -> Act -> Verify -> Report ``` ## UI/UX 原则 Quipu 的界面并不会一次性展示所有日志和指标。在对比了最新的 dashboard、 design system 和 progressive disclosure 案例后，我们采用了深色 `Command Center` 风格，而非简单的卡片式仪表盘。首屏强有力地展示了针对单一事件的四个回答 以及核心 signal console。 - 现在应该检查什么？ - 为什么重要？ - 下一步行动是什么？ - 需要哪些证据才能说明问题已解决？ 详细证据在默认状态下以摘要形式折叠，只有在鼠标悬停、键盘聚焦或按钮 点击流程中才会展开。核心 CTA 固定为 `Review evidence`、`Record action` 和 `Verify result`。 对于 CPU package、Load Average、NVMe 等核心指标，我们不仅仅展示数字。 每个 metric 卡片上的信息按钮会同时显示韩文说明和英文技术术语。 例如，它会明确指出 Load 值代表的是 Linux 1分钟 load average， 而非瞬时的 CPU 使用率。 仅靠 CPU、Load 和 NVMe 虽有助于进行初步的热量评估 (thermal triage)， 但对于团队级别的原因分析却远远不够。因此，目前的 UI 将 Wi-Fi signal 提升 为核心 signal，并在 `Telemetry Matrix` 中同时展示 Memory、Fan RPM、NVMe Health、 Disk Health、Battery Power、Network Events、Reconnect History、Thermal Throttling、 Kernel Warnings 和 Agent Freshness。未来，我们将以相同的结构扩展至更深度的 SMART/NVMe health 分析以及侧重于 fan-context 而非 fan-control 的分析。 v0.9.0 版本的 UI 在此基础上增加了 `Operations Rail`、`Team Handoff` 和 `Pattern Explorer`。运营轨道 (Operations Rail) 在一行内展示 agent freshness、 offline buffer、enrollment guard 和 pattern radar；团队交接 (Team Handoff) 允许针对各个调查项留下备忘；而模式探索 (Pattern Explorer) 则将基于 category/model/kernel 的重复信号进行分组展示。 制作人和版本信息仅保留为页眉处一个微小的 metadata chip。由于大篇幅的 创作者/参考图片区域对调查判断没有直接帮助，因此已被移除。 ## 为什么选择 Quipu 开发设备的故障往往难以用单一指标来解释。CPU 温度、kernel 日志、GPU 驱动警告、 SSD 状态、Wi-Fi 质量、系统更新、启动历史，甚至是桌面上的物理摆放， 都可能同时产生影响。 Quipu 将传感器数值、系统事件以及人员尝试的干预措施整合为一份调查记录。 - 当前状态 - 事件时间线 - 根因假设 - 支持证据与反对证据 - 下一步检查项 - 人员执行的干预措施 - 前后对比 - 供团队分享的报告 ## 差异化特性 1. **调查优先，指标次之** Quipu 从机器、事件和团队问题出发，仅提取为解释问题所必需的指标。 2. **结论关联证据** 每一项判断都必须同时展示支持证据、反对证据、置信度以及原始来源。 3. **团队级别的模式记忆** 系统设计初衷是寻找基于 model、kernel、GPU 驱动、SSD、Wi-Fi 设备、workload 和物理布局的重复性问题。 4. **干预措施验证** 记录诸如稍微抬起笔记本、更改电源配置文件或更新驱动器等干预措施， 并对比干预前后的健康状态。 5. **只读与本地优先的可靠性** 首款产品必须能在团队设备上安全运行。Agent 是只读的，存储为自行托管 (self-hosted)， 且不存在远程修复指令。 ## 当前状态 Quipu 是一个早期的本地优先原型。 已实现： - FastAPI ingest API - 基于 SQLite WAL 的存储 - 基于规则的 fleet overview - 确定性的样本设备数据 - Investigation queue/detail API - 只读 Linux collector - collector 的 best-effort kernel thermal throttling 及 NetworkManager reconnect event 摘要收集 - collector 的 root filesystem 使用率、电池剩余电量、AC 连接状态收集 - collector 的 best-effort kernel storage 及 power warning event 摘要收集 - collector 基于 hwmon 的 Fan RPM 及基于 sysfs 的 NVMe SMART-lite health 收集 - collector 的基于 dry-run、interval 和 iterations 的轻量级运行循环 - collector 的 offline local ring buffer、flush limit、retry backoff - collector 的 systemd service/timer、环境变量文件示例、wrapper 以及 dry-run 安装/卸载脚本 - collector 对 graphics、memory、update、reboot marker 摘要的收集 - device enrollment、per-device token ingest、token rotation/revocation API - schema version endpoint 以及针对调查条目的 team handoff note API - 基于 category/model/kernel 的 Pattern Explorer API - 针对调查条目的 intervention 记录 - intervention 前后的验证结果 - Vite React 以调查为中心的 UI - 高对比度深色 Command Center 首页、核心 signal console、hover/focus 展开面板 - 针对 CPU、Load、NVMe、Wi-Fi 核心指标的韩文说明、英文技术术语、时间窗口、解读说明及下一步检查 tooltip - 整合了 Memory、Fan RPM、NVMe Health、Disk Health、Battery Power、Network Events、Reconnect History、Thermal Throttling、Kernel Warnings 和 Agent Freshness 的 Telemetry Matrix - Operations Rail、Team Handoff、Pattern Explorer UI - 始终可见的微型 Made by、About、Version metadata chip - 用于服务器、collector 和 Web 测试与构建的 GitHub Actions CI 未来规划： - 基于角色的团队工作流、redaction、retention policy - Postgres adapter、backup/restore、longer-term baseline analytics - package publishing 及 production deployment 准备 ## 快速开始 运行包含样本数据的 API 服务器。 ``` scripts/dev-server.sh ``` 在另一个终端中运行 Web UI。 ``` cd apps/web npm install npm run dev ``` 在浏览器中打开。 ``` http://127.0.0.1:5173 ``` ## Collector collector 无需 root 权限即可读取 Linux 信号，并将其输出为 Quipu observation batch。默认为 one-shot 执行，如果提供 `--interval` 参数，则可在轻量级重复 收集循环下运行。它不会执行修复命令，也不会上传完整的原始日志。 目前收集的主要信号： - `cpu.load_1m`: Linux 1分钟 load average - `memory.used_percent`: 基于 `/proc/meminfo` 的内存使用率 - `disk.root_used_percent`: root filesystem 使用率 - `cpu.package_temp_c`, `thermal.*.temp_c`: sysfs thermal zone 温度 - `nvme.temp_c`: 暴露给 hwmon 的 NVMe 温度 - `fan.rpm`: 暴露给 hwmon 的第一个风扇的转速 - `nvme.critical_warning`, `nvme.available_spare_percent`, `nvme.percentage_used_percent`, `nvme.media_errors`: 暴露给 sysfs 的 NVMe SMART-lite health - `wifi.signal_dbm`: 基于 `/proc/net/wireless` 的 Wi-Fi 信号 - `battery.capacity_percent`, `battery.ac_online`: 基于 `/sys/class/power_supply` 的电池/AC 状态 - kernel thermal、storage、power、graphics、memory 警告摘要，update/reboot marker 以及 NetworkManager reconnect 摘要 本地输出： ``` cd apps/collector python -m venv .venv . .venv/bin/activate pip install -e . quipu-collector --dry-run ``` 单次发送至本地 Quipu 服务器： ``` quipu-collector --server-url http://127.0.0.1:8000 --token dev-token ``` 为防止服务器短暂宕机或网络中断时丢失 batch，可将其缓存至本地 spool。 ``` quipu-collector \ --server-url http://127.0.0.1:8000 \ --token "$QUIPU_AGENT_TOKEN" \ --offline-buffer \ --spool-dir ~/.local/state/quipu/collector-spool ``` 设备专属的收集 token 由开发/admin token 生成，随后仅用于该设备的 ingest。 ``` curl -sS -X POST http://127.0.0.1:8000/api/enrollment/tokens \ -H "Content-Type: application/json" \ -H "X-Quipu-Agent-Token: dev-token" \ -d '{"device_id":"thinkpad-p1","label":"ThinkPad P1 collector"}' ``` 重复收集的冒烟测试 (smoke test)： ``` quipu-collector --dry-run --interval 60 --iterations 3 ``` 简单的受监管循环 (supervised loop)： ``` quipu-collector --server-url http://127.0.0.1:8000 --token dev-token --interval 300 ``` systemd timer 安装预览： ``` scripts/install-collector-systemd.sh --dry-run ``` 实际安装流程： ``` sudo scripts/install-collector-systemd.sh --no-enable sudoedit /etc/quipu/collector.env sudo systemctl enable --now quipu-collector.timer systemctl list-timers quipu-collector.timer ``` 卸载： ``` sudo scripts/uninstall-collector-systemd.sh ``` 安装脚本假定目标设备上已安装 `quipu-collector` 可执行文件。 目前暂不包含 package publishing 和 production deployment。 ## 架构 ``` Linux collector | v FastAPI ingest API | v SQLite WAL store | v Rule-based analysis engine | v React investigation UI ``` MVP 边界： - 默认为自行托管 (self-hosted) - 只读收集 - 不执行远程指令 - 不进行自动修复 - 不依赖云服务 - 避免建立全量原始日志仓库 (full raw-log warehouse) ## 验证 服务器： ``` cd apps/server . .venv/bin/activate pytest -v ``` Collector： ``` cd apps/collector python -m venv .venv . .venv/bin/activate pip install -e ".[test]" pytest -v ``` Web： ``` cd apps/web npm test npm run build ``` ## 仓库结构 ``` apps/ collector/ 읽기 전용 Linux observation collector server/ FastAPI API, SQLite persistence, rule-based analysis web/ Vite React UI docs/ superpowers/ 제품 결정, 설계, 계획, 대시보드 fixtures/ ingest/ 결정적 샘플 health batch scripts/ dev-server.sh 로컬 seeded API server ``` ## 核心文档 - [项目仪表盘](docs/superpowers/DASHBOARD.md) - [决策日志](docs/superpowers/DECISION_LOG.md) - [路线图](docs/superpowers/ROADMAP.md) - [发布检查清单](docs/superpowers/SHIP_CHECKLIST.md) - [更新日志](CHANGELOG.md) - [贡献指南](CONTRIBUTING.md) - [安全政策](SECURITY.md) ## 安全边界 当前及近未来的默认设置： - 只读数据收集 - 自行托管 (self-hosted) 存储 - 最小限度日志提取 - 不执行远程指令 - 不进行自动修复 - AI 结论在没有证据链接的情况下不具备权威性 ## 许可证 目前尚未选择许可证。在添加明确的许可证之前，请勿假定拥有再分发权限。

标签：逆向工具