内容
# korg — Ken's organizer
`korg` 将 `kwi`（工作项）和 `kcard`（看板）统一为一个自托管应用：一个类型化的节点 + 通用的边数据模型，一个无头 Linux 后端，以及一个可从 Windows 浏览器访问的 Web UI。
> 状态：**里程碑 1 — 可靠的数据基础。** `kwi` 和 `kcard` 仍然是活跃的工具，并且保持 **冻结 / 只读**，直到 `korg` 可以证明可以接管。
## 文档
- [docs/setup.md](docs/setup.md) — 安装、配置、构建和运行。
- [docs/usage.md](docs/usage.md) — Web UI、REST API 和 MCP 端点。
- [docs/migration.md](docs/migration.md) — 导入旧的 `kwi` 和 `kcard` 数据。
## 模型
所有内容都是一个 **节点**，共享一个代理 ID 空间，因此任何类型都可以通过一个通用的 `关系` 边链接到其他类型：
- **工作项** — 保持一个稳定的、面向用户的序列化 `wi_number`（被外部项目文档引用），它不是主键。
- **卡片** — 看板卡片（状态、排名、标签）。
- *(后续)* 日历时间盒插槽、阅读列表 URL。
跨越属性（项目、类别、标签、存档、时间戳）存在于 `节点`。项目是一个统一的分类法（`kwi` 和 `kcard` 按名称合并）；区域保持项目范围；标签/类别在类型之间共享。
## 工具包
- `korg-core` — 模式（sqlx 迁移）、领域仓库（工作项、卡片、阅读列表链接、通用关系）和日历插槽。
- `korg-migrate` — 一次性、保真度验证的 `kwi` 和 `kcard` 数据导入。
- `korg-mcp` — `korg` 领域的 MCP 工具表面（rmcp），由 `korg-api` 提供服务。
## MCP 服务器
MCP 服务器安装在 `korg-api` 内部，位于 `POST /mcp`，使用 rmcp 的 Streamable-HTTP 传输。因此，一个 `korg-api` 二进制文件同时提供 Web UI、REST API 和 MCP 端点 — 开发/客户端机器不需要安装任何内容；将 MCP 客户端指向 URL：
```
http://<主机>:8090/mcp
```
它公开了 16 个用于工作项、卡片、阅读列表链接、通用跨类型关系和日历时间盒插槽的工具，直接由 `korg-core` 支持。
传输说明：
- **无状态模式**，带有 JSON 响应 — 每个 POST 请求都是一个独立的请求/响应（无 SSE 会话需要管理），适合单用户工具。
- **主机检查禁用**（`disable_allowed_hosts`），因此 `korg` 可以通过受信任网络上的任何主机名访问 — 与 REST API 相同的无身份验证姿态。
针对正在运行的 `korg-api` 进行快速烟雾测试：
```bash
curl -s -X POST http://localhost:8090/mcp \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-H 'mcp-protocol-version: 2025-06-18' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```
## Web UI
`korg-api`（axum）公开 REST API 并在 `KORG_WEB_DIR` 指向构建时提供 SvelteKit 包。
```bash
cd web && pnpm install && pnpm build
DATABASE_URL=... KORG_WEB_DIR=$PWD/build KORG_LISTEN_ADDR=0.0.0.0:8090 \
cargo run -p korg-api # 打开 http://<主机>:8090
# 或在运行的 API 上进行 UI 热重载：
cd web && KORG_API=http://localhost:8090 pnpm dev # http://localhost:5173
```
针对正在运行的 `korg-api` 运行端到端烟雾测试（Playwright/Chromium）：
```bash
cd web
npx playwright install chromium # 一次
KORG_E2E_URL=http://127.0.0.1:8090 npx playwright test
```
## 迁移和保真度
导入操作基于冻结的、只读的 `pg_dump` 快照 — 源数据库从不被修改。
```bash
# 1. 快照实时源（只读）。
KCARD_DOCKER_CONTAINER=kcard-pg \
KCARD_ENV_FILE=../kcard/deploy/local/.env \
just snapshot
# 2a. 验证保真度不变性 F1-F7（CI 样式门控，临时数据库）。
just verify-import
# 2b. 或将数据加载到真正的 `korg` 数据库（--reset 先清除它）。
KORG_DATABASE_URL=postgres://korg:korg@主机:5432/korg just import --reset
```
`verify-import` 证明导入对两个源都是忠实的：计数一致性、`wi_number` 保留（+ 序列在 max+1 继续）、字段到字段完整性、关系和父层次保留、项目合并和项目范围区域。
## 许可证
[MIT](LICENSE) © Ken Hiatt
