# python_claude_tsk_mng

**Repository Path**: enzoism/python_claude_tsk_mng

## Basic Information

- **Project Name**: python_claude_tsk_mng
- **Description**: python开发的claudecode的OpenSpec任务管理系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-28
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# python-claude-tsk-mng

OpenSpec 任务同步与远程执行工具：把本机 OpenSpec 项目的任务列表与执行状态推送到远程服务器，通过手机可访问的网页看板随时查看，还支持在网页上新建任务下发到本地自动执行、对中断任务一键恢复。

链路：`本地代理（agent）⇄ 服务器存储与 API（serve）⇄ 手机网页看板`。

## 组件

- **代理（agent）**：循环执行三步——① 扫描项目 `openspec/changes/` 并推送任务状态；② 拉取服务器上网页创建的任务（origin=web），落地为本地 change 目录（写 proposal.md 与 status.json）并触发执行命令；③ 拉取并执行恢复指令（对目标任务重跑执行命令，依托 tasks.md 勾选进度续跑），完成后向服务器确认。
- **扫描器（scan）**：agent 的子集，仅做扫描推送（只上报、不执行），适合只读上报场景。
- **服务端（serve）**：FastAPI + SQLite。任务接收/查询、网页建任务、恢复指令下发/拉取/确认，并在根路径托管看板页面。
- **看板**：响应式单页（手机单列），30 秒轮询自动刷新；支持新建任务（下发本地执行）、对 failed/paused 任务下发恢复指令。

## 环境要求

- Python ≥ 3.11.4
- [uv](https://docs.astral.sh/uv/)（安装：`curl -LsSf https://astral.sh/uv/install.sh | sh`）
- 代理机（运行 `agent` 的机器）额外需要：
  - 可用的 `claude` CLI（内置默认执行模板依赖它完成任务执行）
  - 需要任务成果截图时，安装浏览器内核：`uv sync && uv run playwright install chromium`

## 本地开发

```bash
uv sync          # 安装依赖
uv run pytest    # 运行测试
```

## 服务器部署

服务端只需 Python + uv，无需安装 claude CLI 与 Playwright。

```bash
# 1. 获取代码并安装依赖
git clone <仓库地址> /opt/python_claude_tsk_mng
cd /opt/python_claude_tsk_mng
uv sync

# 2. 配置令牌（必填，用于写接口与代理接口鉴权）
export TSK_MNG_API_TOKEN="你的随机长令牌"
# 可选：export TSK_MNG_DB_PATH="/var/lib/tsk-mng/tasks.db"
# 可选：export TSK_MNG_UPLOADS_DIR="/var/lib/tsk-mng/uploads"

# 3. 启动（保持单 worker；旧数据库启动时自动补列迁移）
uv run tsk-mng serve --host 127.0.0.1 --port 8000
```

生产环境建议用 systemd 托管，示例 `/etc/systemd/system/tsk-mng.service`：

```ini
[Unit]
Description=python-claude-tsk-mng server
After=network.target

[Service]
WorkingDirectory=/opt/python_claude_tsk_mng
Environment=TSK_MNG_API_TOKEN=你的随机长令牌
Environment=TSK_MNG_DB_PATH=/var/lib/tsk-mng/tasks.db
ExecStart=/opt/python_claude_tsk_mng/.venv/bin/tsk-mng serve --host 127.0.0.1 --port 8000
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now tsk-mng
```

建议用 Nginx 反向代理并配置 TLS：

```nginx
server {
    listen 443 ssl;
    server_name tasks.example.com;
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
    }
}
```

## 本地代理

```bash
# 手动跑一轮（扫描推送 + 落地执行 + 恢复处理）
uv run tsk-mng agent --project /path/to/your/project \
    --server https://tasks.example.com --token 与服务端一致的令牌

# cron 注册（每 5 分钟一轮）
*/5 * * * * cd /path/to/python_claude_tsk_mng && uv run tsk-mng agent --project /path/to/your/project --server https://tasks.example.com --token <令牌>
```

其他参数与说明：

- `--interval N`：以秒为间隔循环运行（缺省单轮后退出）。
- `--executor '<命令模板>'`：自定义执行命令，支持占位符 `{project_root}` 与 `{change_id}`；未配置时使用内置默认模板（调用 `claude` CLI 无头模式，读取 change 目录内 proposal.md 按 OpenSpec 工作流完成变更）。环境变量 `TSK_MNG_EXECUTOR_COMMAND` 亦可。
- 环境变量可代替参数：`TSK_MNG_PROJECT_ROOT` / `TSK_MNG_SERVER_URL` / `TSK_MNG_SERVER_TOKEN`。
- 注意：每个项目路径只运行一个 agent；`agent` 需要运行在装有执行器（如 claude CLI）的机器上。
- 只需上报状态、不需要远程执行时，可用 `tsk-mng scan` 替换 `agent`（参数相同，去掉 `--executor`）。

## 环境变量一览

所有环境变量统一使用 `TSK_MNG_` 前缀；命令行参数优先于环境变量。

| 环境变量 | 使用方 | 必填 | 说明 |
|---|---|---|---|
| `TSK_MNG_API_TOKEN` | serve | 是 | 写接口与代理接口的鉴权令牌 |
| `TSK_MNG_DB_PATH` | serve | 否 | SQLite 数据库路径，默认当前目录 `tasks.db` |
| `TSK_MNG_UPLOADS_DIR` | serve | 否 | 截图上传目录，默认数据库文件同级 `uploads/` |
| `TSK_MNG_PROJECT_ROOT` | agent / scan | 否 | 项目根目录，可代替 `--project` |
| `TSK_MNG_SERVER_URL` | agent / scan | 否 | 服务端地址，可代替 `--server` |
| `TSK_MNG_SERVER_TOKEN` | agent / scan | 否 | 服务端令牌，可代替 `--token` |
| `TSK_MNG_EXECUTOR_COMMAND` | agent | 否 | 执行命令模板，可代替 `--executor` |

## 端到端截图（任务成果验收）

任务执行成功后，代理会检查 change 目录下的截图清单 `screenshots.json`，用 Playwright（Chromium，桌面视口全页截图）逐页截图并上传到服务器，关联到该任务；看板任务卡片上直接展示缩略图，点击可查看原图。

```json
[
  {"name": "首页", "url": "http://127.0.0.1:8000/"},
  {"name": "详情页", "url": "http://127.0.0.1:8000/items/1"}
]
```

- **清单由谁写**：内置默认执行模板已要求 claude 在完成 Web 类任务后写入该清单并保持网站短暂可访问；非 Web 任务没有清单，自动跳过截图。
- **代理机安装**（playwright 已在依赖中，还需浏览器内核）：

  ```bash
  uv sync
  uv run playwright install chromium
  ```

  未安装浏览器内核时截图自动跳过，不影响任务执行状态。
- **服务端存储**：截图保存在 uploads 目录（缺省为数据库文件同级 `uploads/`，可用 `TSK_MNG_UPLOADS_DIR` 配置），经 `/uploads/` 静态路径免鉴权访问，单张上限 10MB、仅接受 PNG/JPEG。

## 网页操作

- **新建任务**：填写标题（必填）与描述提交，服务器生成 `web-` 前缀任务，本地代理下一轮拉取后落地执行。
- **恢复**：`failed`/`paused` 任务卡片上有「恢复」按钮，下发后代理下一轮重跑该任务的执行命令。

## 状态文件约定（status.json）

执行器（agent 或人工）在 change 目录下维护 `status.json`，扫描器据此上报状态：

```json
{"status": "in_progress", "updated_at": "2026-08-28T10:00:00"}
```

`status` 取值：`pending` / `in_progress` / `completed` / `failed` / `paused`。

## 安全提示

- 看板的查询与写操作（新建任务、恢复指令）均为**免鉴权**接口：任何能访问该网址的人都可以向你的开发机注入任务（任务描述会进入 claude 的提示词）。请务必：通过 TLS 反向代理暴露、不公开分享网址，并在 Nginx 上配置 Basic Auth 或 IP 白名单。
- 代理的执行命令通过 `shell` 执行本机配置的模板；服务端只下发任务 id（服务端生成的 id 经过字符集约束），任务描述只写入文件、不进入 shell。不要把执行模板配置来源交给远端。
- `TSK_MNG_API_TOKEN` 用于扫描推送与代理拉取/确认接口；令牌通过环境变量注入，不要写入代码或提交到仓库。