rewelo

Rewelo

警告： 这是实验性软件，不提供支持，也不适用于生产环境。

这是一款使用相对权重法，按不同标准为故事和工单排序的优先级工具。它基于 SQLite（Node 内置的 node:sqlite），提供嵌入式、零依赖的数据存储，可通过命令行界面使用，也可作为基于 Docker 的 MCP 服务运行。

• 网站和文档
• 博客文章
• 最初的想法

工作原理

每个工单都根据敏捷斐波那契数列（1、2、3、5、8、13、21），从四个维度进行评分：

维度	衡量内容
收益	实现该故事所获得的价值
损失	不实现该故事的代价
估算	实现所需的资源
风险	实现过程中的不确定性或复杂性

工具会根据这些数据在运行时计算优先级：

Value    = Benefit + Penalty
Cost     = Estimate + Risk
Priority = Value / Cost

优先级越高，投资回报越好。相对权重会对整个待办列表或带标签的子集（例如某项功能）中的分数进行归一化。完整规范请参阅 calculations.md。

标签

工单通过灵活的标签系统进行组织，标签采用 prefix:value 键值对。标签可替代用于状态、功能分组及其他分类的固定字段：

• state:backlog、state:wip、state:done
• feature:checkout、feature:auth
• team:platform、priority:critical

工单上的每次标签添加和移除都会记录在审计日志中，因此可以根据 state: 标签的变更计算前置时间和周期时间。

修订历史

工具会在两个层面维护完整的修订历史：

• 工单修订 —— 每次变更前的内容（标题、描述、分数）和标签快照
• 标签修订 —— 重命名或编辑标签定义（前缀、值）前的快照

这意味着你可以还原任意工单在任意时间点的确切状态。

数据模型

数据库架构定义在 db/create.sql，并以 DBML 格式记录在 db/model.dbml。

projects
  +-- tickets              (B, P, E, R scores)
  |     +-- ticket_revisions     (content + tag snapshots)
  +-- tags                 (prefix:value pairs)
  |     +-- tag_revisions
  +-- ticket_tags          (current assignments)
  +-- ticket_tag_changes   (audit log: added/removed)
  +-- ticket_relations     (blocks, depends-on, relates-to)
  +-- ticket_deletions     (deleted tickets, for project diff)
  +-- weight_configs       (per-project B/P/E/R weights)

技术栈

• SQLite —— 通过 Node 内置的 node:sqlite 提供嵌入式数据库，无需服务器或原生模块
• TypeScript —— 命令行应用和业务逻辑
• Commander.js —— 命令行界面
• Docker —— 容器化部署，也可用作 MCP 服务

命令行命令

rw project create|list|delete|history|diff
                                    Manage projects, view history and changes
rw ticket  create|list|update|upsert|delete|history
                                    Manage tickets and view revision history
rw tag     create|assign|remove|delete|list|rename|log
                                    Manage tags and view audit log
rw relation create|remove|list|list-all
                                    Ticket relations (blocks, depends-on, relates-to)
rw config  weights                  View/set/reset per-project B/P/E/R weights
rw calc    weights|priority         Relative weights and weighted priority calculations
rw export  csv|json                 Export project data
rw import  csv|json                 Import project data
rw report  summary|group|distribution|health|times|dashboard|event-log
                                    Reporting, HTML dashboard and event stream
rw serve                            Start MCP server (stdio transport)

全局选项：--db <path>、--json、--csv、--quiet（以及为兼容性而接受的 --no-color：rw 从不输出彩色内容）

多项目支持

该工具以项目为最高层级边界进行设计。标签、工单和所有计算均限定在各自项目内，因此多个团队或产品可以独立使用同一个实例。

发布新版本

.github/workflows/ 中的 4 个 GitHub Actions 工作流负责构建、发布和分发：

工作流	运行时机	执行内容
ci.yml	向 main 推送和提交拉取请求	类型检查、构建、测试，并对 Docker 镜像进行冒烟测试
release.yml	推送 v* 标签时	检查标签是否与 package.json 一致，运行测试，并创建包含 npm tarball、SBOM、OCI 镜像和更新日志的 GitHub Release；将镜像推送到 ghcr.io/sebs/rewelo
publish.yml	手动运行（提供版本号）	通过可信发布将指定标签版本发布到 npm，并提供来源证明，然后将其登记到 MCP Registry，名称为 io.github.sebs/rewelo
pages.yml	向 main 推送时	从 site/ 和文档构建网站，并将其部署到 GitHub Pages

发布步骤：

1. 更新版本号，此操作会提交更改（其中的 server.json 和 MCP Registry 条目会设置为相同版本），并创建对应的标签：

npm version patch   # 0.1.0 → 0.1.1 (or minor, major)

2. 推送提交和标签；release.yml 将构建发布版本：

git push --follow-tags

3. 发布到 npm：使用新版本号运行 Publish 工作流（Actions → Publish → Run workflow），或运行 gh workflow run publish.yml -f version=0.1.1。npm 上显示该版本后，工作流也会将其登记到 MCP Registry（mcp-publisher 使用工作流的 GitHub OIDC 令牌登录，因此无需密钥）。预发布版本（如 0.2.0-beta.1）会使用 next dist-tag 发布；低于当前最新版本的回移版本（如当前为 0.6.1，而回移版本为 0.5.2）会使用 backport dist-tag 发布，因此 npm install rewelo 始终会安装最新的稳定版本。

一次性设置：在 npmjs.com 上将 sebs/rewelo 添加为 rewelo 包的可信发布者，并将 Settings → Pages → Source 设置为 “GitHub Actions”。

运行已发布的镜像：

# CLI
docker run --rm -v rw-data:/data ghcr.io/sebs/rewelo:latest project list

# MCP server
docker run --rm -i -v rw-data:/data ghcr.io/sebs/rewelo:latest serve

使用命名卷（rw-data）或绑定挂载，以便在容器重启后保留数据库。若未使用卷或挂载，数据库会留在容器内，并在容器被移除时丢失（使用 --read-only 时则完全无法写入）；rw 会通过标准错误流警告此问题。

MCP 服务

CLI 也可通过 stdio 充当 MCP 服务，让 AI 助手直接管理项目、工单、标签和计算。客户端配置、可用工具及故障排除，请参阅 mcp.md。

示例

请参阅 examples.md，了解分步操作场景。每个场景都提供可复制粘贴的 Claude Code 提示词（MCP）和带输出的 rw 命令，涵盖 CSV 导入、依赖关系映射、自定义权重、快速见效的改进、工作跟踪、脚本编写，以及待办事项列表的共享和备份。