kaiord

Kaiord —— 开源健康与健身数据框架

kaiord.com | 编辑器 | npm

Kaiord 是一个用于创建、转换和管理健康与健身数据的开源框架。

它提供：

• @kaiord/core：一个 TypeScript 库，提供适用于 .fit、.tcx、.zwo 和 .krd（Kaiord）文件的格式适配器，并集成 Garmin Connect API。
• @kaiord/cli：一个命令行工具，用于在不同格式之间转换、验证和比较文件。
• @kaiord/mcp：一个 MCP 服务，向 AI Agent 提供 Kaiord 工具（Claude Desktop、Claude Code 等）。已以 io.github.pablo-albaladejo/kaiord 的名称发布在官方 MCP 注册表中。
• 训练编辑器：一个用于直观创建和编辑训练文件的 Web 应用。

---

✨ 功能

• 可视化训练编辑器 - 在浏览器中创建和编辑训练
• 统一的 JSON 格式 .krd（Kaiord Representation Definition）
• Schema 验证（Zod）
• 在 FIT / TCX / ZWO / GCN / KRD 格式之间安全地往返转换
• 六边形架构和完全类型化的 API

支持的 FIT 字段

训练元数据

• 子运动分类：详细的运动类型（越野跑、室内骑行、泳池游泳等）
• 泳池尺寸：游泳训练的泳池长度和单位

训练步骤

• 指导备注：每个步骤的说明文字（最多 256 个字符）
• 游泳装备：脚蹼、浮板、划水掌、夹腿浮球、呼吸管

时长类型

• 时间和距离：标准间歇时长
• 基于卡路里：达到指定消耗卡路里数后结束的步骤
• 基于功率：达到功率阈值（瓦特）后结束的步骤
• 心率条件：达到心率阈值（bpm）后结束的步骤
• 重复条件：重复区块，直到达到时间／距离／卡路里／心率／功率目标

已知限制

• 训练压力分数（TSS）：FIT 转换器尚未实现 training_peaks_tss 时长类型。这是 TrainingPeaks 专用指标，需要额外的映射逻辑。欢迎贡献！

🔒 本地优先架构

Kaiord 采用本地优先架构：数据保存在你的设备上，因为没有 Kaiord 服务可以接收数据。无需账户，也没有后端。

• 数据存储在浏览器的 IndexedDB 中。Workout Editor 会将每个训练、模板、个人资料和设置保存在本地 Dexie.js / IndexedDB 数据库中（dexie-database.ts 中的 new KaiordDatabase()），并通过 useLiveQuery 以响应式方式读取数据。数据不会写入远程数据库——请参阅 State Management 中的“Persisted data → Dexie”规则。
• **转换完全在你的设备上运行。**FIT / TCX / ZWO / GCN ↔ KRD 转换在进程内完成——在编辑器中由客户端执行（import-workout-formats.ts、export-workout-formats.ts），或由 @kaiord/cli 在本地执行。文件不会离开你的设备进行转换。
• **同步为可选功能，数据会同步到_你自己的_云端。**只有连接 Google Drive 时，数据才会离开设备。cloud-sync 适配器 使用 Google Identity Services 的 drive.appdata 作用域，因此同步的数据会存放在你自己的 Drive 应用文件夹中；访问令牌仅在会话期间保存在内存中，Kaiord 不会持久化该令牌。
• **集成使用_你自己的_登录会话——不代理凭据。**Garmin、WHOOP 和 Train2Go 通过浏览器扩展“桥接程序”连接（garmin-bridge、whoop-bridge、train2go-bridge），并借助你现有的浏览器会话。根据 openspec/specs/adapter-contracts/spec.md，桥接程序“不得存储、传输或管理用户凭据”；身份验证“完全交由浏览器的 Cookie 存储区处理”。没有第三方服务会代理你的凭据或数据。
• **支持离线使用。**由于所有逻辑和存储都在客户端运行，编辑器加载完成后，即使没有网络连接也能继续使用。

---

📚 文档

/docs 目录中提供了完整的文档：

• 入门指南 - 安装、基本用法，以及库和 CLI 的快速示例
• 架构 - 六边形架构、端口与适配器模式以及设计原则
• 测试 - 测试策略、TDD 工作流和覆盖率要求
• 部署 - CI/CD 流水线、GitHub Pages 部署和 npm 发布
• 贡献指南 - 贡献指南、开发工作流和代码规范
• KRD 格式 - Kaiord Representation Definition 格式的完整规范
• AI Agent - AI 辅助开发指南

---

🧩 技术栈

层级	工具
核心	TypeScript、tsdown、Zod
CLI	yargs
Web 应用	React、Zustand、Tailwind、Radix UI
测试	Vitest、Playwright
包管理器	pnpm

---

🏗 Monorepo 目录结构

kaiord/
├─ packages/
│  ├─ core/                → domain types, schemas, ports & use cases
│  ├─ fit/                 → Garmin FIT format adapter
│  ├─ tcx/                 → Training Center XML adapter
│  ├─ zwo/                 → Zwift ZWO format adapter
│  ├─ garmin/              → Garmin Connect API adapter
│  ├─ cli/                 → command-line interface
│  ├─ mcp/                 → MCP server for AI/LLM integration
│  └─ workout-spa-editor/  → web application (https://kaiord.com/app/)
├─ docs/   → documentation
├─ LICENSE
├─ README.md
└─ pnpm-workspace.yaml

---

🚀 快速开始

试用 Web 应用

启动 Workout Editor →

在浏览器中直观地创建和编辑训练。无需安装。

使用库

pnpm install
pnpm -r build
pnpm -r test

# Example usage
pnpm kaiord --help

如需详细的安装说明和使用示例，请参阅**入门指南**。

---

🚀 CI/CD 流水线

Kaiord 使用 GitHub Actions 进行持续集成和部署：

• 自动化测试：在 Node.js 22.x（维护版 LTS）和 24.x（活跃版 LTS）上进行多版本测试
• 代码质量：ESLint、Prettier 和 TypeScript 严格模式验证
• 发布自动化：使用 Changesets 进行版本管理和 npm 发布
• 安全性：每周进行依赖项漏洞审计、CodeQL 静态分析和自动依赖项更新

如需完整的 CI/CD 文档、部署指南和 npm 发布说明，请参阅 部署。

机械化不变量防护

除 lint 检查外，仓库还通过 scripts/ 下 60 多个专用防护脚本来确保架构和规范得到遵守，每个脚本都有各自配套的测试套件。它们会在每次提交时（husky pre-commit）以及 CI 中（pnpm test:scripts）运行，检查内容包括：

• 六边形架构 — 层级纯粹性、适配器隔离，以及 packages/core/src/ 目录允许列表（check-architecture.mjs）
• 包依赖关系图 — 每个 @kaiord/* 依赖项都必须符合规范表（check-package-deps.mjs）
• 测试规范 — 每个测试的标题都必须以 should 开头，并采用 Arrange/Act/Assert 结构（check-test-title-should.mjs、check-test-aaa.mjs）
• 隐私 — 不得将运行时值插入 Toast 或控制台日志（check-no-pii-leakage.mjs）
• 状态管理规范 — Zustand store 不得直接写入持久化存储（check-no-zustand-writethrough.mjs）
• 规范维护 — OpenSpec 格式、归档日期和自动生成的索引保持同步（check-spec-format.mjs、check-archive-*.mjs）

如果某条规则在这里很重要，就会有脚本强制执行——文档描述规则，而防护脚本确保规则得到落实。

参与贡献

为 Kaiord 贡献代码：

1. Fork 并克隆仓库
2. 创建功能分支：git checkout -b feature/my-feature
3. 按照代码风格指南修改代码
4. 添加 changeset：pnpm exec changeset（适用于需要发布新版本的变更）
5. 在本地测试：pnpm -r test 和 pnpm -r build
6. 提交 PR：合并前必须通过所有检查

如需详细的贡献指南、开发工作流和代码规范，请参阅 贡献指南。

---

📚 参考资料与资源

格式规范

• Garmin FIT SDK (JavaScript) - 官方 FIT 协议实现
• FIT Workout Files Cookbook - 编码训练文件指南
• FIT File Types: Workout - 训练文件类型规范
• Training Center XML (TCX) - Garmin 基于 XML 的格式
• TCX Schema (XSD) - Garmin 官方 TCX 架构定义
• Zwift Workout Format (ZWO) - Zwift 基于 XML 的训练格式

---

❤️ 支持

如果你觉得 Kaiord 很有用，可以考虑支持它的开发：

• ⭐ 为此仓库点 Star，帮助更多人发现它
• 💖 在 GitHub 上赞助
• ☕ 请我喝杯咖啡

你的支持有助于为健身社区维护和改进 Kaiord！

由 Pablo Albaladejo 创建

---

📜 许可证

MIT © 2025 Pablo Albaladejo 详情请参阅 LICENSE。