| name | dev |
| description | my-labs 仓库开发指南。当用户说"加个 skill"、"新增命令"、"这个项目怎么构建"、 "目录结构是什么"、"怎么跑起来"、"加个功能"、"改一下 CLI"时要触发。 涵盖 monorepo 工作流、Skill/CLI/Extension 的选择决策、TypeScript 规范、构建流程。 在 my-labs 仓库中做任何代码变更前先读此技能。 |
my-labs 开发指南
项目总体规划见 AGENTS.md。本技能聚焦具体操作，AGENTS.md 聚焦架构决策。
快速启动
pnpm install
pnpm build
pnpm test
为什么要先 build？ Turborepo 的 test 和 lint 任务依赖 ^build（上游包先构建），
所以 pnpm test 会自动触发必要的构建。但首次克隆后建议显式 pnpm build 确保一切就绪。
三层产出：什么时候建什么
my-labs 有三种产出类型，选择逻辑如下：
| 场景 | 建什么 | 位置 |
|---|
| Agent 需要领域知识/工作流指导（纯 Markdown） | Skill | packages/skills/<name>/ |
| 需要命令行交互、脚本化操作 | CLI 命令 | packages/cli/src/commands/ |
| 编辑器 UI 扩展（VS Code / Raycast） | Extension | packages/extensions/<name>/ |
简单口诀：首选 Skill（零构建成本，git 即分发），Skill 不够用时加 CLI 命令，编辑器交互才建 Extension。
新增 Skill
在 packages/skills/<name>/ 下创建 SKILL.md 即可，无需构建。
命名规则：目录名 = name 字段，全小写 + 连字符（如 my-skill-name）。
SKILL.md 模板：
---
name: my-skill
description: 清晰的触发描述——这是 Agent 决定是否调用此技能的唯一依据
---
# Skill 标题
写给 Agent 的指令...
目录可包含辅助资源（模板、脚本等），在 SKILL.md 中通过相对路径引用：
packages/skills/my-skill/
├── SKILL.md
├── templates/ # 代码模板
└── references/ # 参考文档（Agent 按需加载）
详细 Skill 编写规范见 @skill-creator 技能。
新增 CLI 命令
CLI 基于 oclif v4，源文件在 packages/cli/src/commands/。
实现步骤
- 创建 Command 类：
import { Command } from "@oclif/core";
export default class MyCommand extends Command {
static description = "命令描述";
async run(): Promise<void> {
this.log("Hello from my-cli!");
}
}
- 验证命令已注册：
cd packages/cli
pnpm build
node bin/run.js my-command --help
命名映射
- 文件名即命令名：
hello.ts → my-cli hello
- 子目录映射为子命令：
admin/status.ts → my-cli admin status
关键约定
- 模块系统：ESM（
"type": "module"），输出到 dist/
tsconfig.json 必须 extends 自 ../../tsconfig.base.json- 命令描述用
static description（oclif 自动生成 help）
TypeScript 规范
根目录 tsconfig.base.json 已设定共享基线。各包子目录的 tsconfig.json 只需：
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src"]
}
核心约束：
- 目标 ES2022，严格模式开启
- CLI 使用
"module": "NodeNext"，其他包使用 "module": "ESNext"
- 每个包独立编译，通过 Turborepo 编排依赖顺序
构建流水线
Turborepo 任务依赖（定义在 turbo.json）：
| 任务 | 依赖 | 说明 |
|---|
build | ^build | 先构建依赖包，再构建自身 |
lint | ^build | 依赖包构建后执行 |
test | ^build | 依赖包构建后执行 |
dev | 无 | 无缓存，持续运行 |
clean | 无 | 无缓存 |
新增 Extension
在 packages/extensions/<name>/ 下创建新包，确保：
package.json 中 name 以 @gaorun/ 开头- 遵循上述 TypeScript 规范
修改后必做事项
- 更新 AGENTS.md — 第 7 节「已有 Skill 清单」和第 8 节「迭代记录」
- 更新 README.md — 用户文档同步变更
- 运行完整构建 —
pnpm build && pnpm test
测试相关细节见 @test 技能，发布细节见 @deploy 技能。
