Purple-Horizons/tick-md

✨ 功能特色

• 🤖 AI 原生支援：提供 MCP 伺服器，無縫整合機器人
• 📝 人類可讀：使用 YAML 前言（frontmatter）的純 Markdown 格式
• 🔄 Git 備份：完整的版本控制與自動稽核軌跡
• 🎯 依賴追蹤：自動解除任務封鎖
• 🔒 檔案鎖定：防止並行編輯衝突
• 🔍 進階篩選：依狀態、優先級、標籤搜尋任務
• 📊 視覺化：依賴圖（ASCII 與 Mermaid）
• 👀 即時監控：監看模式，取得即時更新
• 🌐 本地優先：無需雲端，可離線運作

🚀 快速開始

安裝 CLI

npm install -g tick-md

初始化專案

cd your-project
tick init
tick status

建立與認領任務

tick add "Build authentication" --priority high --tags backend
tick claim TASK-001 @yourname
tick done TASK-001 @yourname

🤖 給 AI 代理的說明

安裝 MCP 伺服器

npm install -g tick-mcp-server

在你的 MCP 設定檔中新增（例如 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "tick": {
      "command": "tick-mcp",
      "args": [],
      "env": {}
    }
  }
}

使用 MCP 工具

MCP 伺服器將所有 CLI 指令公開為工具：

• tick_init - 初始化專案
• tick_add - 建立任務
• tick_claim - 為你的代理認領任務
• tick_done - 標記任務完成
• tick_status - 取得專案概覽
• tick_list - 查詢與篩選任務
• tick_comment - 新增進度備註

🎯 核心概念

TICK.md 檔案結構

---
meta:
  project_id: my-project
  id_prefix: TASK
  next_id: 4
  updated: 2026-02-07T15:30:00-05:00
---

### TASK-001 · Build user authentication

```yaml
id: TASK-001
status: in_progress
priority: high
claimed_by: @claude-code
assigned_to: @claude-code
created_by: @gianni
created_at: 2026-02-07T10:00:00-05:00
updated_at: 2026-02-07T15:30:00-05:00
tags: [backend, auth]
depends_on: []
blocks: [TASK-002, TASK-003]
history:
  - ts: 2026-02-07T10:00:00  who: @gianni       action: created
  - ts: 2026-02-07T15:30:00  who: @claude-code  action: claimed

Build JWT-based authentication with refresh tokens

### 自動 Git 提交

預設情況下，每次變更都會建立一個 Git 提交：
```bash
[tick] TASK-001 claimed by @claude-code
[tick] TASK-001 completed by @claude-code
[tick] TASK-003: created

可使用以下旗標控制：

• --commit - 強制提交
• --no-commit - 跳過提交
• 或在 .tick/config.yml 中設定

任務狀態

• backlog - 尚未準備開始
• todo - 可以認領
• in_progress - 正在處理中
• review - 等待審查
• blocked - 等待依賴任務
• done - 已完成

檔案鎖定

CLI 使用 .tick.lock 防止並行編輯。當代理認領任務時，它會取得鎖定。其他代理會看到任務已被認領，無法修改。

📚 文件

• 協定規格：https://tick.md/docs/protocol
• CLI 參考：https://tick.md/docs/cli
• 入門指南：https://tick.md/docs/getting-started

💡 範例工作流程

# 人類建立任務
tick add "Build landing page" --priority high --tags frontend --assign @claude-code
tick add "Write launch email" --priority medium --tags content --assign @content-bot
tick add "E2E tests" --priority medium --tags qa --depends-on TASK-001

# AI 代理開始工作
tick claim TASK-001 @claude-code
tick comment TASK-001 @claude-code --note "Built responsive landing with hero section"
tick done TASK-001 @claude-code

# 另一個代理自動觸發
tick claim TASK-003 @qa-bot
tick done TASK-003 @qa-bot --skip-review

🔧 設定

編輯 .tick/config.yml：

git:
  auto_commit: true      # 變更時自動提交（預設：true）
  commit_prefix: "[tick]"
  push_on_sync: false

locking:
  enabled: true
  timeout: 300

agents:
  default_trust: full
  require_registration: false

🌟 OpenClaw 機器人最佳實踐

1. 工作前務必先認領：tick claim TASK-XXX @yourbotname
2. 新增進度備註：tick comment TASK-XXX @yourbotname --note "Status update"
3. 完成時標記為完成：tick done TASK-XXX @yourbotname
4. 檢查依賴：使用 tick list --blocked 查找被封鎖的任務
5. 使用 MCP 伺服器：支援自然語言任務管理

🔧 OpenClaw 多代理設定

逐步指南，教你如何透過 TICK.md 協調多個 OpenClaw 機器人。

1. 建立共享任務倉庫

gh repo create yourorg/project-tasks --private
cd project-tasks
npx tick-md init
git add -A && git commit -m "init" && git push

2. 在每個 OpenClaw 機器人的伺服器上

cd /data/.openclaw/workspace
git clone [email protected]:yourorg/project-tasks.git tasks
cd tasks && npx tick-md status

3. 新增到每個機器人的 AGENTS.md

## ✅ 任務協調（TICK.md）

我透過 `./tasks/` 中的 TICK.md 與其他代理協調。

### 開始工作前：
1. `cd tasks && npx tick-md sync` — 取得最新狀態
2. `npx tick-md list --status backlog --priority high` — 尋找可用的工作
3. `npx tick-md claim TASK-XXX @mybotname` — 工作前先認領
4. `npx tick-md done TASK-XXX @mybotname` — 標記完成

### 規則：
- **絕不處理其他代理已認領的任務**
- **開始工作前務必先認領**
- **工作前後都要同步**

4. 新增到每個機器人的 HEARTBEAT.md

## 任務同步（TICK.md）

- [ ] 同步任務：`cd tasks && npx tick-md sync`
- [ ] 檢查我的工作：`npx tick-md list --claimed-by @mybotname --status in_progress`
- [ ] 檢查可用任務：`npx tick-md list --status backlog --priority high`

5. 部署金鑰

每個機器人需要 SSH 存取共享倉庫。在每台伺服器上產生部署金鑰：

ssh-keygen -t ed25519 -C "botname@tasks" -f ~/.ssh/tasks_deploy -N ""
cat ~/.ssh/tasks_deploy.pub
# 將此金鑰新增到倉庫 Settings → Deploy Keys（並啟用寫入權限）

設定 Git 使用該金鑰：

cd tasks
git config core.sshCommand "ssh -i ~/.ssh/tasks_deploy -o IdentitiesOnly=yes"

6. 機器人的同步指令

在執行任何 tick 變更後，推送變更：

cd tasks && git push

或者使用 tick sync，它會自動處理拉取和推送。

📦 套件資訊

• CLI：npm 上的 tick-md
• MCP 伺服器：npm 上的 tick-mcp-server
• GitHub：https://github.com/Purple-Horizons/tick-md
• 授權：MIT

🆘 支援

• GitHub Issues：https://github.com/Purple-Horizons/tick-md/issues
• 贊助：https://github.com/sponsors/Purple-Horizons