Metadata-Version: 2.1
Name: zsc
Version: 0.2.2
Summary: AI Agents-driven project task CLI for initializing .agents task structure and skills.
Author: zigslice
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: typer<1.0,>=0.12
Requires-Dist: importlib-metadata>=4.0; python_version < "3.8"

## 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/` 下按需安装这些技能，帮助各工具理解并维护任务体系。
- **幂等执行**：重复运行不会破坏已有结构或覆盖用户已有的技能文件。

### 安装

你可以根据环境选择使用 **pip** 或 **uv tool** 安装 `zsc`：

```bash
# 使用 pip（适用于未安装 uv 或习惯用 pip 的环境）
pip install -U zsc

# 使用 uv tool 作为全局工具（推荐在已安装 uv 时）
uv tool install zsc          # 首次安装
uv tool install zsc --upgrade  # 升级到最新版本
```

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

```bash
uv pip install -e .[test]
```

> 以上命令仅为示例，请根据你的环境和 `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 版本，可运行：

```bash
zsc -V
# 或
zsc --version
```

### 使用 `zsc -U` 升级

在任意终端中，你可以通过：

```bash
zsc -U
```

来尝试将 `zsc` 升级到最新版本：

- 当检测到系统中已安装 `uv` 且当前项目没有损坏的 `.venv` 时，`zsc -U` 会优先调用 `uv tool install zsc --upgrade` 进行升级（与 `uv tool install zsc --upgrade` 等价）。
- 当检测到 `.venv` 中的 Python 解释器是断裂的符号链接（例如 `.venv/bin/python3` 已失效）时，`zsc -U` 会跳过基于 uv 的升级，直接回退为 `pip install -U zsc`，并在输出中提示你考虑用 `uv venv` 或其他方式重建虚拟环境。
- 当 uv 可用但升级失败（包括 uv 报错 `No virtual environment found; run \`uv venv\` to create an environment, or pass \`--system\` to install into a non-virtual environment` 这类情况）时，`zsc -U` 会自动尝试一次 `pip install -U zsc` 作为兜底；若兜底仍失败，会在最后给出可复制的手动命令，方便你按需选择 `pip install -U zsc` 或 `uv tool install zsc --system`。
- 实际行为与使用的 Shell 类型（bash/zsh/fish 等）无关，关键在于各 Shell 的 `PATH` 设置指向的是**同一份 `zsc` 可执行文件**。如果某个 Shell 命中的 `zsc` 是安装在虚拟环境中的另一份版本，其 `zsc -U` 行为会跟随该环境而变化。

### 任务管理命令

`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`。

### Skills 命令组（AI 侧命令行）

`zsc` 除了提供传统的终端子命令（如 `zsc init .`、`zsc task list`），还会为各类 AI Coding 工具安装一组以 `zsc-*` 命名的 **skills**。在 AI 环境中，它们就像一套新的「命令行」，由大模型代你在本地项目中执行具体操作。

- **传统 CLI 命令行**：你在终端中直接输入，例如：
  - `zsc init .`
  - `zsc task list`
- **Skills 命令行（AI 侧）**：你在 IDE/AI 工具中触发技能，例如：
  - 在 Cursor 中输入 `/zsc-help`、`/zsc-create-task`、`/zsc-run-task` 等，让 AI 代为执行对应操作。

核心 Skills 一览（名称按安装目录中的 skill 名称）：

- `zsc-help`
  - **职责**：介绍 zsc 的整体用途、CLI 子命令与 skills 之间的对应关系，并给出快速上手示例。
  - **触发方式示例**：在 Cursor 中输入 `/zsc-help`。
  - **关联 CLI/资源**：`zsc --help`、本 README。

- `zsc-create-task`
  - **职责**：仅负责在 `.agents/tasks` 下创建与设计任务（闭环描述与 `TODO_LIST`），不执行具体 TODO。
  - **触发方式示例**：`/zsc-create-task @task_xx_xxx.md`。
  - **关联 CLI/资源**：`zsc task new`；任务文件位于 `.agents/tasks/task_{no}_{feat_name}/task_{no}_{feat_name}.md`。

- `zsc-run-task`
  - **职责**：执行并推进已有任务，根据 `TODO_LIST` 实际修改代码/文档，完成后重写 `TODO_LIST` 为完成记录。
  - **触发方式示例**：`/zsc-run-task @task_02_xxx.md`。
  - **关联 CLI/资源**：操作 `.agents/tasks` 下的任务文件与对应代码/文档，本身不直接对应某个 `zsc task` 子命令。

- `zsc-run-task-to-complete`
  - **职责**：在安全环境下，尽可能一口气自动执行指定任务中的多个 TODO，减少中途交互，最后按同样的收口规范重写 `TODO_LIST`。
  - **触发方式示例**：`/zsc-run-task-to-complete @.agents/tasks/task_06_zsc_run_task_to_complete/task_06_zsc_run_task_to_complete.md`。
  - **关联 CLI/资源**：基于 `.agents/tasks` 下的任务文件工作，属于构建在 `zsc-run-task` 之上的高级、高自动化执行模式，适合在 Feature 分支或非生产环境中使用。

- `zsc-task-list`
  - **职责**：从 AI 侧列出 `.agents/tasks` 下已有任务及状态，帮助快速浏览任务闭环。
  - **触发方式示例**：`/zsc-task-list`。
  - **关联 CLI/资源**：`zsc task list`。

- `zsc-task-status`
  - **职责**：总结项目级任务健康度（open/completed/unknown 数量）。
  - **触发方式示例**：`/zsc-task-status`。
  - **关联 CLI/资源**：`zsc task status`。

- `zsc-update-task`
  - **职责**：仅更新任务设计（闭环描述、`TODO_LIST` 等），不执行 TODO。
  - **触发方式示例**：`/zsc-update-task @task_03_init_lang_prompt.md`。
  - **关联 CLI/资源**：`zsc task update`。

> 维护约定：新增或删除 zsc-* skills 时，请同步更新本节，保持与 `.cursor/skills/` 等目录中的实际安装内容一致。

### TODO 设计原则：让 TODO 可落地、可收口

- **每个 TODO 都应尽量是具体可执行的工程动作**：能大致描述「谁在什么上下文里要做什么」，并适合作为 1–2 小时内可完成的子任务。
- **避免把长期观察/跟踪类事项或过于抽象的目标写进 TODO_LIST**：例如「持续观察错误率」「保证系统长期稳定」更适合作为：
  - 单独的任务（专门的监控/稳定性任务），或
  - 记录在 `task_records/log/`、设计文档或运维文档中，而不是长期挂在某个任务的 TODO 列表里。
- **采用自底向上的拆解方式**：优先写“下一步可以落地的具体动作”，子任务完成后再为下一步设计新的 TODO；当发现某个 TODO 过大或含糊时，优先拆分为多个更小、更具体的新 TODO 来替换它。

