zsc 0.1.8

AI Agents-driven project task CLI for initializing .agents task structure and skills.

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：

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

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

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

uv pip install -e .[test]

以上命令仅为示例，请根据你的环境和 uv 版本适当调整。

使用

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

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 版本，可运行：

zsc -V
# 或
zsc --version

使用 zsc -U 升级

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

zsc -U

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

• 当检测到系统中已安装 uv 且当前项目没有损坏的 .venv 时，zsc -U 会优先调用 uv tool install zsc --upgrade 进行升级。
• 当检测到 .venv 中的 Python 解释器是断裂的符号链接（例如 .venv/bin/python3 已失效）时，zsc -U 会跳过基于 uv 的升级，直接回退为 pip install -U zsc，并在输出中提示你考虑用 uv venv 或其他方式重建虚拟环境。
• 当 uv 可用但升级失败时，zsc -U 也会自动尝试一次 pip install -U zsc 作为兜底，并在最终失败时给出可复制的手动命令。

任务管理命令

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。