zsc（全称 zig slice code）是一个面向多 IDE/AI Coding 工具的命令行工具，用于在项目中初始化统一的 AI Agents 任务体系。
语言 / Language: 中文 | English
你可以根据环境选择使用 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版本适当调整。
- 初始化
.agents任务目录结构：创建.agents/与.agents/tasks/，作为项目级任务闭环与 TODO 的统一入口。 - 为多种 AI Coding 工具安装
zsc-*技能：除zsc init外，每个子命令对应一个技能（如zsc-create-task对应zsc task new）。zsc init会在.cursor/skills/、.codex/skills/、.claudecode/skills/下按需安装这些技能，帮助各工具理解并维护任务体系。 - 幂等执行：重复运行不会破坏已有结构或覆盖用户已有的技能文件。
在目标项目根目录中运行：
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 升级到最新版本：
- 当检测到系统中已安装
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。
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 代为执行对应操作。
- 在 Cursor 中输入
核心 Skills 一览（名称按安装目录中的 skill 名称）：
| 技能 | 职责 | 触发示例 | 关联 CLI |
|---|---|---|---|
| zsc-help | 介绍 zsc 用途、CLI 与 skills 对应关系及上手示例。 | /zsc-help |
zsc --help、README |
| zsc-create-task | 仅在 .agents/tasks 下创建与设计任务（闭环描述与 TODO_LIST），不执行 TODO。 |
/zsc-create-task @task_xx.md |
zsc task new |
| zsc-run-task | 执行并推进已有任务，按 TODO_LIST 修改代码/文档，完成后重写 TODO_LIST。 | /zsc-run-task @task_02_xxx.md |
— |
| zsc-run-task-to-complete | 在安全环境下尽量一口气自动执行多个 TODO，减少交互，按同样收口规范重写 TODO_LIST。 | /zsc-run-task-to-complete @task_06_...md |
— |
| zsc-task-list | 从 AI 侧列出 .agents/tasks 下任务及状态。 |
/zsc-task-list |
zsc task list |
| zsc-task-status | 总结项目级任务健康度（open/completed/unknown 数量）。 | /zsc-task-status |
zsc task status |
| zsc-update-task | 仅更新任务设计（闭环描述、TODO_LIST 等），不执行 TODO。 | /zsc-update-task @task_03_xxx.md |
— |
维护约定：新增或删除 zsc-* skills 时，请同步更新本节，保持与
.cursor/skills/等目录中的实际安装内容一致。
- 每个 TODO 都应尽量是具体可执行的工程动作：能大致描述「谁在什么上下文里要做什么」，并适合作为 1–2 小时内可完成的子任务。
- 避免把长期观察/跟踪类事项或过于抽象的目标写进 TODO_LIST：例如「持续观察错误率」「保证系统长期稳定」更适合作为单独的任务或记录在
task_records/log/、设计文档或运维文档中，而不是长期挂在某个任务的 TODO 列表里。 - 采用自底向上的拆解方式：优先写“下一步可以落地的具体动作”，子任务完成后再为下一步设计新的 TODO；当发现某个 TODO 过大或含糊时，优先拆分为多个更小、更具体的新 TODO 来替换它。