内容
# clickup-tracker
[](./LICENSE)
[](https://github.com/Achitokun14/clickup-tracker-standalone/actions/workflows/ci.yml)
[](./docker-compose.yml)
[](./mcp/README.md)
> 自托管的 Docker 守护进程，可将本地 Git 仓库镜像到 ClickUp 任务中。每次提交和每次 Claude Code / Goose / OpenCode 会话都会自动成为跟踪事件，并带有备份和一键恢复功能。
```
git commit ─┐
├─→ clickup-tracker (:4020) ─→ ClickUp
agent turn ──┘ ├─ 每个仓库一个文件夹
├─ 列表：提交记录
├─ 列表：提示信息
└─ 列表：概览与文档
```
## 30秒快速入门
```bash
git clone https://github.com/Achitokun14/clickup-tracker-standalone
cd clickup-tracker-standalone
cp .env.example .env # 填写 CLICKUP_API_TOKEN 和 CLICKUP_TEAM_ID
bash install.sh # docker compose up + MCP 构建 + 配置写入
```
就这样。守护进程现在在 `http://localhost:4020` 运行。要连接您的 AI 编码代理，请运行以下任意命令：
```bash
bash install.sh --agent claude-code # Claude Code (~/.claude/)
bash install.sh --agent claude-compat # OpenClaw / ZeroClaw / ClawCode
bash install.sh --agent opencode # OpenCode
bash install.sh --agent all # 自动检测已安装的代理
```
在 Windows 上：`.\install.ps1 -Agent claude-code` （需要 Git for Windows + Docker Desktop）。
参见 [`docs/quickstart.md`](./docs/quickstart.md) 以获取完整的 5 分钟快速入门指南。
## 为什么使用此工具
- **停止重复编写任务。** 守护进程将提交记录转换为 ClickUp 任务，包含结构化字段（变更日志条目、待办事项、涉及的文件）。
- **AI 会话也会显示。** Claude Code / Goose / OpenCode 提示信息和结果会与提交记录一起镜像。
- **自托管，AGPL。** 在您的笔记本电脑或服务器上运行。无 SaaS，无遥测，无分析。
- **备份 + 恢复。** 在风险操作前快照 ClickUp 树。一键恢复。
- **抗漂移。** 5 分钟漂移 cron 自动协调 ClickUp ⟷ git。
## 代理集成矩阵
| 代理 | 原生支持 | 安装命令 | 文档 |
|---|---|---|---|
| Claude Code | 斜杠命令 + 停止/提示钩子 + MCP | `bash install.sh --agent claude-code` | [docs/integrations/claude-code.md](./docs/integrations/claude-code.md) |
| OpenClaw / ZeroClaw / ClawCode | 共享 `~/.claude/` 约定 | `bash install.sh --agent claude-compat` | [docs/integrations/claude-compat.md](./docs/integrations/claude-compat.md) |
| Goose | 配方 + MCP 扩展 | `bash install.sh --agent goose` | [docs/integrations/goose.md](./docs/integrations/goose.md) |
| OpenCode | 斜杠命令 + MCP | `bash install.sh --agent opencode` | [docs/integrations/opencode.md](./docs/integrations/opencode.md) |
| Cursor / Cline / Continue / 通用 MCP | 通用 MCP 服务器 | 手动 JSON 配置 | [docs/integrations/generic-mcp.md](./docs/integrations/generic-mcp.md) |
| 无 MCP 支持 | 原始 HTTP | `curl` 示例 | [docs/integrations/http-direct.md](./docs/integrations/http-direct.md) |
## 架构
```
┌──────────────┐ 提交后钩子 ┌──────────────────────┐ ┌─────────┐
│ 跟踪仓库 │ ────HMAC-SHA256────▶ │ clickup-tracker │ ─▶ │ ClickUp │
└──────────────┘ │ (NestJS @ :4020) │ │ REST │
│ ┌────────────────┐ │ └─────────┘
┌──────────────┐ 停止 / 提示 │ │ Postgres + Redis│ │
│ Claude Code │ ────HMAC-SHA256────▶ │ │ (独立卷) │ │
│ Goose │ │ └────────────────┘ │
│ OpenCode │ MCP 标准输入/输出 │ + 5 分钟漂移 cron │
│ + 任意 MCP │ ─────────────────▶ │ + 批量规划器 │
└──────────────┘ └──────────────────────┘
```
完整图表：[`docs/architecture.md`](./docs/architecture.md)。
## 端点
所有端点均在 `http://localhost:4020/` 公开（可通过 `TRACKER_PORT` 覆盖）。
| 方法 | 路径 | 认证 | 目的 |
|---|---|---|---|
| GET | `/health` | 无 | 存活探测 |
| GET | `/projects` | bearer（如果设置了 `STANDALONE_API_TOKEN`） | 列出跟踪项目 |
| POST | `/projects` | bearer | 注册仓库，返回 `hookSecret` 一次 |
| GET | `/projects/:id` | bearer | 详情 |
| PATCH | `/projects/:id` | bearer | 更新名称 / 状态 |
| DELETE | `/projects/:id?wipe=true` | bearer | 取消跟踪（自动预移除备份） |
| POST | `/projects/:id/sync` | bearer | 排队立即漂移同步 |
| POST | `/projects/:id/backup` | bearer | 手动快照 |
| GET | `/projects/:id/backups` | bearer | 列出快照 |
| POST | `/projects/:id/restore` | bearer | 从备份恢复 |
| GET | `/projects/resolve?path=` | bearer | 最长前缀路径 → 项目 ID |
| POST | `/public/git-events` | HMAC | 提交后 Webhook |
| POST | `/public/prompt-events` | HMAC | 代理停止钩子 Webhook |
| GET | `/public/metrics` | bearer（如果设置了 `METRICS_AUTH_TOKEN`） | Prometheus |
| GET | `/public/openapi.yaml` | 无 | 完整的 OpenAPI 3.1 规范 |
## 布局
```
clickup-tracker-standalone/
├── install.sh / install.ps1 # 一键多平台安装程序
├── docker-compose.yml # postgres + redis + tracker, 重启：始终
├── .env.example # CLICKUP_API_TOKEN, 端口, 可选旋钮
├── CREDS.md # 您需要哪些凭证 + 在哪里获取它们
├── SECRETS.md.example # 您的本地秘密包模板
├── service/ # NestJS 守护进程（端口 4020）
│ ├── Dockerfile
│ ├── prisma/schema.prisma
│ ├── openapi.yaml
│ └── src/ # 主项目, 事件, 批量, 同步, 备份, clickup
├── mcp/ # 通用 MCP 服务器（Node, 标准输入/输出）
│ └── src/server.ts
├── agents/ # 每个代理的集成垫片
│ ├── claude-code/ # 7 斜杠命令 + 2 钩子 + 安装程序
│ ├── claude-compat/ # OpenClaw / ZeroClaw / ClawCode 包装器
│ ├── goose/ # 配方 + MCP 扩展
│ ├── opencode/ # 命令 + MCP 配置
│ ├── generic-mcp/ # 任意 MCP 客户端
│ └── http-direct/ # 原始 HTTP（TS/Python/Go 代码段）
├── scripts/
│ ├── self-setup.sh # 旧版引导（由 install.sh 委托）
│ ├── install-git-hook.sh # 将提交后钩子放入跟踪仓库
│ └── windows/ # PowerShell 包装器用于 Win
├── schema/init.sql # clickup_tracker 架构
└── docs/ # 快速入门, 架构, 部署, …
```
## 跨平台支持
| 平台 | 状态 | 备注 |
|---|---|---|
| Linux（任意现代发行版） | ✅ 一流 | 通过 `docker.io` 包或 Docker CE 的 Docker |
| macOS | ✅ 一流 | Docker Desktop 或 Colima |
| Windows | ✅ 通过 Git Bash 或 WSL2 | 需要 Docker Desktop；`install.ps1` 包装 `install.sh` |
Bash 脚本针对 Bash 4+。Python **不** 需要 — 仅需要 `bash`、`jq`、`openssl`、`curl`、`docker` 和（对于 MCP 服务器）`node`。
## 停止 / 删除
```bash
docker compose down # 停止，保持数据卷
docker compose down -v # 销毁包括数据（cup_pgdata, cup_redisdata）
```
## 文档
**基础**
- [快速入门](./docs/quickstart.md) — 5 分钟端到端
- [架构](./docs/architecture.md) — 组件，序列，ER 图（mermaid）
- [API 参考](./docs/api-reference.md) — 完整端点表 + 认证
- [部署](./docs/deployment.md) — Docker，反向代理，TLS
- [故障排除](./docs/troubleshooting.md) — 常见故障
- [FAQ](./docs/faq.md) — 许可证，隐私，代理兼容
- [Windows](./docs/windows.md) — Git Bash 与 WSL2，Docker Desktop 备注
**功能深入解析（v0.3.0+）**
- [SCRUM 操作员](./docs/scrum-operator.md) — 自主冲刺规划器 / 整理器 / 报告 + 7 个自主不变性
- [SCRUM 跟踪工件](./docs/scrum-tracked-artifacts.md) — CU 中完整目录
- [多开发者采用](./docs/multi-developer.md) — 在 N 个守护进程之间共享一个工作区
- [GitHub 身份桥接](./docs/github-identity.md) — 阶段 F（提交电子邮件 → 缓存 GitHub 登录 + 头像）
- [自定义字段和视图](./docs/custom-fields-and-views.md) — 阶段 E 参考
- [空间模型](./docs/space-model.md) — 每个仓库的空间布局
- [运行手册](./docs/runbook.md) — 操作员手册（备份，恢复，重建）
- [路线图](./docs/roadmap.md) — 已发布里程碑 + v0.5.0（阶段 I–N）预览
**操作**
- [凭证](./CREDS.md) — 需要设置什么，在哪里获取令牌
- [安全策略](./SECURITY.md) — 私人报告 + 轮换指南
- [贡献](./CONTRIBUTING.md) — 开发设置 + PR 流程
- [变更日志](./CHANGELOG.md)
## 许可证
[AGPL-3.0-or-later](./LICENSE)。如果您作为网络服务（SaaS）运行修改后的版本，则必须在相同许可证下发布您的修改。
连接信息
猜你喜欢
暂无推荐服务器