Smart Trellis

smart-trellis 是 Trellis 的智能初始化与联调增强包。它保留原 Trellis 的完整项目结构，同时把常见初始化选项收束成更少、更明确的配置入口。

这个 npm 包提供三个命令：

smart-trellis  # 智能初始化入口
trellis        # 原 Trellis CLI
tl             # trellis 的短别名

当前 npm latest：0.5.23。

安装

npm install -g @ibotor/smart-trellis@latest

安装后，在项目根目录执行：

smart-trellis init

如果希望临时使用，也可以不全局安装：

npx -p @ibotor/smart-trellis smart-trellis init

smart-trellis 迭代功能

1. smart-trellis init

smart-trellis init 用来简化 Trellis 初始化配置。它会调用原始 trellis init，但提前帮你处理常见默认值，让新项目更快进入可用状态。

核心能力：

| 能力 | 说明 | 常用参数 | | --- | --- | --- | | 简化 Trellis 初始化配置 | 默认启用非交互初始化，自动检测 monorepo、开发者名称和常用 AI 工具 | --yes、--tools、--user | | 配置触发方式 | 支持用户主动触发，或让 Trellis 在开发请求中自动判断是否进入任务流程 | --trellis-activation explicit、--trellis-activation auto | | 配置 .gitignore | 初始化时可选择是否把 .trellis/ 和 AI 工具生成目录加入 .gitignore | --gitignore-config、--no-gitignore-config |

推荐的新项目初始化方式：

smart-trellis init \
  --tools codex,cursor \
  --user <developer-name> \
  --trellis-activation explicit \
  --gitignore-config

如果希望完全使用默认配置：

smart-trellis init --yes

--yes 会使用默认工具 codex,cursor，并把 .trellis/、.codex/、.cursor/、.agents/skills/ 等生成目录写入 .gitignore。

初始化时会生成什么

根据选择的工具不同，生成内容会略有差异。常见输出包括：

| 路径 | 作用 | | --- | --- | | .trellis/ | Trellis workflow、spec、tasks、workspace、脚本等核心目录 | | .agents/skills/ | 跨工具复用的 Trellis skills | | .codex/ | Codex 专用配置、agents、hooks、skills | | .cursor/ | Cursor 专用 commands、skills、agents、hooks | | .github/ | GitHub Copilot prompts、agents、hooks 等 | | AGENTS.md | 项目级 AI 助手协作说明 |

触发方式配置

smart-trellis init 支持配置 Trellis 的 activation mode：

| 模式 | 行为 | 适合场景 | | --- | --- | --- | | explicit | 用户明确说 /trellis start、$trellis-start、走 Trellis 等才启动任务流程 | 希望普通问答和小改动不被 Trellis 接管 | | auto | Trellis 根据当前开发请求自动判断是否进入任务流程 | 希望 AI 主动进入 Trellis 工作流 |

示例：

smart-trellis init --tools codex,cursor --trellis-activation explicit

旧项目可以先更新模板，再在 .trellis/config.yaml 里设置：

trellis update

trellis:
  activation_mode: explicit

.gitignore 配置

初始化时可以选择是否把生成目录加入项目 .gitignore。以 codex,cursor 为例，候选项通常是：

.trellis/
.codex/
.agents/skills/
.cursor/

规则：

• 交互模式下会显示多选项，默认全选。
• 没有 .gitignore 时会创建。
• 已有 .codex 或 .codex/ 时不会重复添加 .codex/。
• 已有 .agents/ 时，不会再重复添加 .agents/skills/。
• 候选目录来自 Trellis 的 AI 工具注册表，不手写平台清单。

脚本模式下直接全选：

smart-trellis init --tools codex,cursor --gitignore-config

完全不修改 .gitignore：

smart-trellis init --tools codex,cursor --no-gitignore-config

注意：如果把 .trellis/ 加入 .gitignore，Trellis 的 spec、tasks、workspace 等状态默认不会被 Git 跟踪。适合把 Trellis 配置当本地工作区的团队；如果团队希望提交 .trellis/spec/ 或任务记录，请在多选时取消 .trellis/。

2. 前后端联调

前后端联调用来让 AI 根据 Apifox 接口链接读取接口详情，并和当前项目里的 API 封装、请求参数、响应字段、代理配置进行对照。

当前真实入口名是 trellis-joint-debugger：

Cursor: /trellis-joint-debugger
Codex / .agents/skills: $trellis-joint-debugger

使用场景：

• 前端已经有页面或 API wrapper，但接口参数对不上。
• 后端接口文档在 Apifox，想让 AI 自动读取 method、path、query、body、response。
• 只想提供 Apifox 链接，让 AI 帮你定位本地代码里该改哪里。

支持的 Apifox 链接格式：

app.apifox.com/link/project/{projectId}/apis/api-{apiId}
app.apifox.com/project/{projectId}/apis/api-{apiId}

第一次使用前，可以保存 Apifox token：

python3 ./.trellis/scripts/apifox_token.py save

也可以检查当前是否已配置：

python3 ./.trellis/scripts/apifox_token.py check

token 读取优先级：

1. APIFOX_ACCESS_TOKEN 环境变量
2. ~/.trellis/apifox.env
3. 旧项目内 .trellis/.runtime/apifox.env

联调流程会做什么：

1. 从 Apifox 链接解析 projectId 和 apiId。
2. 请求 Apifox Web API 读取接口详情。
3. 提取 method、path、query/path/header/body、responses。
4. 展开请求体或响应体里的 schema 引用。
5. 搜索当前项目里的 API 封装、请求客户端、代理配置和环境配置。
6. 对比 Apifox 字段和本地代码字段。
7. 如需真实请求业务后端，会根据项目代理和环境配置执行；如果返回 401 或缺少登录态，会明确报告。

旧项目先运行：

trellis update

常用参数

指定工具

逗号形式：

smart-trellis init --tools codex,cursor,claude

独立参数形式：

smart-trellis init --codex --cursor --claude

当前支持的工具名：

claude
cursor
opencode
codex
kilo
kiro
gemini
antigravity
windsurf
qoder
codebuddy
copilot
droid
pi

指定开发者名称

smart-trellis init --tools codex,cursor --user adong

如果不传 --user，会优先读取 git config user.name，再回退到系统用户名。

Registry 和模板

smart-trellis init 兼容原 trellis init --registry 能力，可以从自定义 GitHub、GitLab、Bitbucket 仓库拉取 spec。

smart-trellis init \
  --tools codex,cursor \
  --registry gh:myorg/myrepo/my-team-spec

Marketplace 模式：

smart-trellis init \
  --tools codex,cursor \
  --registry gh:myorg/myrepo/marketplace \
  --template my-template

指定分支：

smart-trellis init \
  --tools codex,cursor \
  --registry gh:myorg/myrepo/specs#develop

GitLab 和 Bitbucket：

smart-trellis init --tools codex,cursor --registry gitlab:myorg/myrepo/specs
smart-trellis init --tools codex,cursor --registry bitbucket:myorg/myrepo/specs

远程模板写入策略：

smart-trellis init --tools codex,cursor --registry gh:myorg/myrepo/specs --overwrite
smart-trellis init --tools codex,cursor --registry gh:myorg/myrepo/specs --append

文件覆盖和 Monorepo

默认写入策略偏安全：遇到已有文件会跳过，避免覆盖本地配置。

smart-trellis init --tools codex,cursor --force
smart-trellis init --tools codex,cursor --skip-existing

Monorepo 默认自动检测。也可以手动指定：

smart-trellis init --tools codex,cursor --monorepo
smart-trellis init --tools codex,cursor --no-monorepo

更新已有项目

已初始化项目通常只需要：

npm install -g @ibotor/smart-trellis@latest
trellis update

如果要使用 Apifox 联调能力，再配置一次用户级 token：

python3 ./.trellis/scripts/apifox_token.py save

本地开发验证

在本仓库开发时，先构建 CLI：

pnpm --filter @ibotor/smart-trellis build

直接用本地 bin 测试：

node packages/cli/bin/smart-trellis.js init --tools codex,cursor --user adong

也可以在临时项目里验证：

mkdir /tmp/smart-trellis-demo
cd /tmp/smart-trellis-demo
echo '{"name":"smart-trellis-demo"}' > package.json
node /path/to/smart-trellis/packages/cli/bin/smart-trellis.js init --tools codex,cursor --user adong

发布前建议至少运行：

pnpm --filter @ibotor/smart-trellis test
pnpm --filter @ibotor/smart-trellis build
pnpm --filter @ibotor/smart-trellis lint
pnpm --filter @ibotor/smart-trellis typecheck