## zsc

`zsc` 是一个面向多 IDE/AI Coding 工具的命令行工具，用于在项目中初始化统一的 AI Agents 任务体系。

核心能力：

- **初始化 `.agents` 任务目录结构**：创建 `.agents/` 与 `.agents/tasks/`，作为项目级任务闭环与 TODO 的统一入口。
- **为多种 AI Coding 工具安装 `zsc-*` 技能**：除 `zsc init` 外，每个子命令对应一个技能（如 `zsc-create-task` 对应 `zsc task new`）。`zsc init` 会在 `.cursor/skills/`、`.codex/skills/`、`.claudecode/skills/` 下按需安装这些技能，帮助各工具理解并维护任务体系。
- **幂等执行**：重复运行不会破坏已有结构或覆盖用户已有的技能文件。

### 安装

推荐使用 `uv` + `python3`：

```bash
uv add zsc
```

或在本仓库中开发调试时，使用本地安装（示例）：

```bash
uv pip install -e .
```

> 以上命令仅为示例，具体安装方式可根据你的环境和 `uv` 版本调整。

### 使用

在目标项目根目录中运行：

```bash
zsc init .
```

`zsc init .` 将会：

- 创建 `.agents/` 与 `.agents/tasks/` 目录（若不存在）。
- 创建以下 AI 工具技能目录（若不存在）：
  - `.cursor/skills/`
  - `.codex/skills/`
  - `.claudecode/skills/`
- 将打包在 `zsc` 中的各 `zsc-*` 技能复制到上述各技能目录中对应子目录：
  - `.cursor/skills/zsc-help/SKILL.md`（用法介绍，在 AI 环境中可触发如 `/zsc-help` 让 LLM 介绍 zsc 与各技能用法）
  - `.cursor/skills/zsc-create-task/SKILL.md`（对应 `zsc task new`）
  - `.cursor/skills/zsc-task-list/SKILL.md`（对应 `zsc task list`）
  - `.cursor/skills/zsc-task-status/SKILL.md`（对应 `zsc task status`）
  - `.codex/skills/`、`.claudecode/skills/` 下同样按技能名安装。
  - **仅在目标位置不存在该文件时才写入**，避免覆盖用户已有定制。

再次运行 `zsc init .` 时：

- 已存在的目录将被检测并跳过。
- 已存在的 `SKILL.md` 不会被覆盖，只会输出提示。

### 任务管理命令

`zsc` 提供了一组围绕 `.agents/tasks` 的任务管理子命令：

- `zsc task list`：列出 `.agents/tasks` 下的任务及其基本状态（open/completed）。
- `zsc task new <feat_name> [path]`：在指定项目根目录（默认为当前目录）下创建新的 `task_{no}_{feat_name}` 目录与同名文件 `task_{no}_{feat_name}.md` 模板（便于在编辑器中按名称快速打开）。
- `zsc task status`：汇总 `.agents/tasks` 中任务的数量与状态，给出项目级任务健康度摘要。

配合 `zsc init .`，你可以先在项目中初始化任务体系，然后通过 `zsc task` 系列命令持续维护和浏览任务闭环。

> 说明：`zsc task new` 创建任务目录与同名 `.md` 模板。在 AI Coding 工具中触发 **zsc-create-task** 技能（如 Cursor 中 `/zsc-create-task`）时，若用户要求「创建新任务」，AI 会代为执行 `zsc task new <feat_name>` 或按模板创建目录与文件，并可根据需求意图帮你完善“闭环描述”和 `TODO_LIST`。若你此前使用过旧版技能名 `zsc-new-task`，请重新执行 `zsc init .` 以安装为 `zsc-create-task`。

