@blxzer/cursor-trellis

English | 简体中文

Trellis CLI 的 npm 包。项目总览：../../README.zh-CN.md。Cursor 工作流：../../docs/workflow.zh-CN.md。

为何 cstl 与 .cstl/？ CLI 为 cstl（非 trellis），运行时目录为 .cstl/（非 .trellis/），以便与上游 Trellis 在同一仓库共存。详见仓库 README。

安装

npm install -g @blxzer/cursor-trellis

需要 Node.js ≥ 18.17。生成项目的钩子在运行 Cursor 的机器上需要 Python ≥ 3.9。

从 0.3.0 升级（v0.3.1）

v0.3.1 将 cursor-trellis 运行时目录从 .trellis/ 迁至 .cstl/。

npm install -g @blxzer/cursor-trellis@latest
cd /path/to/your-app
cstl update --migrate

--migrate 必须带上；历史通过目录 rename 保留。脚本路径为 python ./.cstl/scripts/...。

从 0.2.x 升级（v0.3.0）

v0.3.0 为硬切更名：CLI 仅保留 cstl，trellis 与 tl 两个 bin 别名已移除。

| 变了 | 没变 | | --- | --- | | CLI：trellis / tl → cstl | （0.3.1+）运行时目录为 .cstl/ | | skill / command / agent / rule：trellis-* → cstl-* | trellis-task-models.json5 文件名 |

迁移步骤（每个项目执行一次）：

npm install -g @blxzer/cursor-trellis@latest
cd /path/to/your-app
cstl update --migrate

--migrate 必须带上，才会重命名 .cursor/ 下的 trellis-* → cstl-*。重命名经哈希校验；若你本地改过文件，会保留旧路径并警告——请手动改名或把自定义内容迁到新的 cstl-* 路径。

0.3.0 之后日常 CLI 小版本可用 cstl upgrade。升级到 0.3.0 后，旧的 trellis upgrade 命令已不存在。

Cursor++ BYOK（可选，仅 .cstl/local/cursor2plus/）：将 trellis-task-models.json5 中的 trellis-research/implement/check 键改为 cstl-research/implement/check，然后重跑 patch_wpelc8.py --apply。可在 Agent 模式使用 /cstl-cursor2plus-setup。

详见 CHANGELOG。

可执行文件

| Bin | 作用 | | --- | --- | | cstl | 在项目中初始化、更新、管理 Trellis | | smart-search | 随包分发的网页检索 CLI（见 smart-search） |

cstl --version
smart-search --version

命令一览（摘要）

| 命令 | 用途 | | --- | --- | | init | 创建 .cstl/ 与所选平台目录 | | update | 将模板同步到当前安装的 CLI 版本 | | uninstall | 从项目中移除 Trellis 管理文件 | | upgrade | 升级全局 CLI npm 包 | | rollout | 对多个项目路径批量 update | | workflow | 工作流模板工具（进阶） |

与 channel 相关的命令服务于进阶多 Agent 工作流，不属于 Cursor-first 公开文档范围。完整列表：cstl --help。

下文详述 init、update、uninstall。

cstl init

在目标项目根目录执行：

cstl init --cursor

平台标志

| 标志 | 平台 | | --- | --- | | --cursor | Cursor（.cursor/）— 默认文档路径 | | --cursor2plus | Cursor++ BYOK 本地包（须同时 --cursor） |

本 fork 的 init 与公开文档为 Cursor-only：../../docs/cursor.zh-CN.md。

常用标志

| 标志 | 说明 | | --- | --- | | -y, --yes | 非交互默认项 | | -f, --force | 覆盖已有受管文件 | | -s, --skip-existing | 跳过已存在文件 | | --cursor2plus | 物化 Cursor++ BYOK 包（须同时 --cursor） | | -u, --user <name> | 开发者身份 | | --skip-readiness | 跳过 smart-search / 能力项 readiness | | --capability <id> | 启用可选能力（可重复；all 表示全部可选） | | --workflow <id> | .cstl/workflow.md 工作流模板 | | -t, --template <name> | 远程 spec 模板 | | -r, --registry <source> | 自定义模板 registry | | --monorepo / --no-monorepo | monorepo 检测覆盖 |

生成内容

• .cstl/ — workflow、spec、tasks、workspace、scripts、模板哈希
• AGENTS.md — 受管说明块
• 平台目录 — Cursor 下为 .cursor/commands、rules、agents、hooks、hooks.json、worktrees.json

cstl update

在已有 .cstl/ 的项目根目录：

cstl update
cstl update --dry-run

标志

| 标志 | 说明 | | --- | --- | | --dry-run | 仅预览不写盘 | | -f, --force | 覆盖所有有变更的受管文件 | | -s, --skip-all | 跳过所有有变更文件 | | -n, --create-new | 对有变更文件写 .new 副本 | | --migrate | 执行待处理路径迁移（重命名/删除） | | --allow-downgrade | 允许模板版本低于记录版本 | | --skip-readiness | 跳过 readiness 复检 | | --json | 单行 JSON rollout 证据 | | --skip-post-update-smoke | 跳过应用后 Python 冒烟脚本 |

常见流程：升级全局 CLI → 进入项目 → cstl update（从 0.2.x 首次升到 0.3.0 须加 --migrate）→ 若自定义过 workflow/rules 请审阅 diff。

cstl uninstall

cstl uninstall
cstl uninstall --dry-run
cstl uninstall -y

标志

| 标志 | 说明 | | --- | --- | | -y, --yes | 跳过确认 | | --dry-run | 仅列出将删除/scrub 的内容 |

按哈希清单与结构化 scrubber 移除受管平台文件及 .cstl/。卸载前请备份自定义 workflow 或 rules。

smart-search 集成

Trellis 集成了 smart-search，这是一个用于 Agent 从网络检索当前信息的 CLI 工具。当你安装 cursor-trellis 时，smart-search 会自动作为依赖安装。

安装：

当你安装 cursor-trellis 时，smart-search 会自动安装：

npm install -g @blxzer/cursor-trellis
# smart-search 现已可用
smart-search --version

链接：

• npm 包：https://www.npmjs.com/package/@blxzer/smart-search
• GitHub 仓库：https://github.com/blxzer77/smart-search

工作流会在 smart-search 可用时，将外部事实查询路由到它。详见仓库了解配置和使用详情。

维护者脚本（本包）

面向编辑本仓库的贡献者，终端用户不必运行：

| 脚本 | 用途 | | --- | --- | | pnpm build | tsc + 拷贝模板 | | pnpm test | Vitest | | pnpm mirror-check | Dogfood .cursor / .agents vs templates | | pnpm run sync:smart-search | 刷新 vendor |

Release 与 npm 发布流程不在公开 README 中；见内部维护文档。

延伸阅读

• 项目 README
• Cursor 集成
• 架构概览
• CHANGELOG