UsrTerills

UsrTerills 是基于 Trellis 改造的公司 AI 前端工程化 CLI。它把项目规范、任务留痕、平台配置、Hook、Agent 和项目级 Skill 安装到业务仓库中，让不同 AI 编程工具共享同一套项目事实与开发约束。

内部运行目录继续使用 .trellis/，已有 migration、Task schema 和 trellis-* 能力名称保持兼容；终端命令使用精确大小写的 usrTerills。

安装

前置环境：

• Node.js >=18.17.0
• Python >=3.9

测试发布阶段安装：

npm install -g @cmx1996/usr-terills@next
usrTerills --version

正式发布切换到 latest 后，将安装命令中的 @next 改为 @latest。

在公司项目中使用

进入业务项目根目录，根据团队实际使用的平台初始化：

usrTerills init --codex --claude --cursor -u your-name

只使用 Codex 时：

usrTerills init --codex -u your-name

初始化会生成或维护：

.trellis/                 项目规范、Task、工作日志、脚本、Agent 与版本状态
AGENTS.md                 跨平台项目入口规则
.<platform>/              对应 AI 工具的 Skill、Hook、命令或配置
.code-review-graph/       项目级代码图谱索引

常用命令：

usrTerills update --dry-run
usrTerills update
usrTerills workflow --list
usrTerills mem search "关键词"
usrTerills platforms
usrTerills upgrade

init 可以重复执行。update 使用 .trellis/.template-hashes.json 区分 CLI 管理内容和用户修改，不会默认覆盖已修改文件。

Skill、Hook 与 Agent

| 能力 | 职责 | 团队如何维护 | | --- | --- | --- | | Skill | 告诉 AI 在什么场景使用什么方法、读取哪些参考文件 | 通用项目能力由 CLI 分发；业务专属能力放项目本地 Skill | | Hook | 在会话开始、提示提交、命令执行等时机注入项目状态或执行保护 | 由 init/update 按平台安装，配置集中在 .trellis/config.yaml | | Agent | 定义可独立执行实现、检查等工作的角色和约束 | 项目级运行时定义位于 .trellis/agents/ | | Spec | 保存可核验的编码约束、目录规则、测试命令与验收标准 | 团队评审后提交到 .trellis/spec/ | | Task | 保存当前需求、设计、实施切片、进度和验证 receipt | 位于 .trellis/tasks/<task>/，面向人的 Markdown 默认中文 |

默认随 CLI 分发的项目级 Skill：

subagent-workflow
github-community
portable-interaction-output
trellis-session-insight
trellis-spec-bootstrap
update-context
direct-workflow
local-evidence-flow

Vue、中文表达、公司 Git、产品版本兼容等个人或组织级 Skill 不随项目 CLI 重复安装，应继续放在用户级 Skill 目录中。

两个项目并行开发

Hook 和 Task 状态均以项目根目录为边界。两个项目分别执行 usrTerills init 后，各自使用自己的 .trellis/、平台配置和 .code-review-graph/，不会共享项目 Task 或模板 hash。

跨项目共享的是 npm CLI 和用户级 Skill。并行开发时仍需遵守以下边界：

• 不要让两个进程同时写同一个项目的同一个 Task。
• 同一项目并行实施使用不同 worktree/workspace，并划分不重叠的写入范围。
• .trellis/.runtime/、备份、缓存、图谱索引等运行文件按项目 .gitignore 管理。

前端同事需要提供什么

AI 前端编程规范必须基于真实项目证据。前端同事至少需要提供以下内容，缺失项应明确标记为“暂无约定”，不要由 AI 猜测：

| 类别 | 需要的证据 | | --- | --- | | 技术栈 | package.json、lockfile、Node/package manager 版本、Vue/React 版本、构建工具 | | 标准命令 | 安装、开发、lint、typecheck、单测、E2E、构建和发布命令 | | 目录边界 | 页面、组件、composable/hook、store、API、类型、样式、测试与静态资源目录职责 | | UI 规范 | Figma 链接或截图、设计 token、组件库、主题、图标库、响应式断点、浏览器范围 | | 数据契约 | API 文档、错误码、鉴权、分页、时区、金额精度、空值和兼容策略 | | 状态与路由 | Router/Store 约定、权限守卫、缓存、页面生命周期和跨页面状态规则 | | 质量门禁 | ESLint/Prettier/Stylelint 配置、测试范围、覆盖要求、CI 必过项 | | 产品差异 | 私有部署、公有云、中性品牌、海外版、功能开关与外部服务可用性 | | Git 与发布 | 实际分支模型、提交规范、合并要求、环境、Tag、回滚和 Hotfix 流程 | | 历史问题 | 高频 Bug、兼容事故、禁止模式、性能瓶颈和已验证解决方案 |

推荐先让 trellis-spec-bootstrap 基于源码和配置生成 .trellis/spec/ 初稿，再由前端负责人逐条确认。规范应写成可检查的触发条件、动作和验收结果，例如明确“修改公共组件后运行什么命令”，而不是只写“遵循最佳实践”。

CLI 品牌与发布

品牌配置唯一入口：

packages/cli/brand.config.json

一键修改包名、命令名、显示名和发布通道：

pnpm brand --package @cmx1996/usr-terills --command usrTerills --display-name UsrTerills --tag next
pnpm brand:check

该命令同步 packages/cli/package.json 的 name 与 bin。新生成的 CLI 帮助、Hook、Skill 和模板命令从品牌配置读取，不需要全仓替换；.trellis/、migration 和内部协议名不会被重命名。

本地打包与安装测试：

pnpm build
pnpm pack:cli

npm 发布：

npm whoami
pnpm publish:package

publish:package 只发布公司 CLI，dist-tag 读取 brand.config.json。@mindfoldhq/trellis-core 继续作为公开运行依赖，不随公司 CLI 重复发布。

许可与来源

本项目基于 Trellis 修改并继续使用 AGPL-3.0-only 许可证。内部改造不会把 npm 包冒充为上游 @mindfoldhq/trellis。