@siyuan0215/cg-frontend

CF / cg-frontend — 前端团队 AI Coding skill pack + CLI。

把可复用的前端规范装进业务仓库：CLI 落盘 Pack 与 config.yaml，IDE 投影薄入口；日常写代码由 Skill 读项目变量，而不是猜技术栈。

Skills 一览

| Skill | 怎么用 | 做什么 | 什么时候用 | |-------|--------|--------|------------| | cg-frontend（CF） | Cursor/Qoder：/cg-frontend 或自动加载；Claude/Copilot：入口文件指向本 Skill | 日常前端生成 / 修改 / 重构时的规范：先读 config.yaml，遵守 constraints.never，按 stack / paths / patterns 写代码 | 已完成配置审阅（confidence: reviewed）后的日常开发 | | cg-frontend-init | Cursor/Qoder： /cg-frontend-init | CLI 装完之后：带你 Review 探测结果、补全空字段、处理 detect.warnings，在你同意后把 meta.confidence 设为 reviewed | 每次 npx … init（或重大改栈重探）之后立刻跑一遍 |

Pack 内正文位于：

• cg-frontend/SKILL.md — 主 Skill
• cg-frontend/skills/cg-frontend-init/SKILL.md — 初始化 Skill
  Cursor / Qoder 还会各投影一份到 .cursor/skills/、.qoder/skills/，以便斜杠命令调用。

初始化步骤（推荐）

在要接入的业务前端仓库根目录操作（不要在本 npm 包源码仓库里跑 npx @siyuan0215/cg-frontend，否则可能出现 cg-frontend: command not found；本仓开发请用 npx . 或 node bin/cg-frontend.js）。

1. 安装 Pack + 探测配置

cd /path/to/your-frontend-app
npx @siyuan0215/cg-frontend init

常用非交互示例：

npx @siyuan0215/cg-frontend init --yes --ide cursor,qoder

CLI 会：

1. 把 Pack 拷到 cg-frontend/
2. 按 package.json / 目录探测并写出 config.yaml、context.md（meta.confidence 为 draft）
3. 按所选 IDE 投影薄入口（含 cg-frontend 与 cg-frontend-init）
4. 打印下一步提示（提醒你跑 /cg-frontend-init）

2. 执行初始化 Skill（必需）

打开 Cursor 或 Qoder，在对话里执行：

/cg-frontend-init

Agent 会按 Skill 引导你：

1. 核对探测到的 stack / paths / patterns
2. 补全空的关键字段（不臆测）
3. 处理 detect.warnings
4. 在你明确同意后，将 meta.confidence 改为 reviewed

没有 Cursor/Qoder 时，可人工编辑 cg-frontend/config.yaml 后自行改 confidence。

3. （可选）自检

npx @siyuan0215/cg-frontend doctor

4. 日常开发

之后前端相关改动由 /cg-frontend（CF） 约束。项目差异只改 config.yaml；团队共性升级 Pack：

npx @siyuan0215/cg-frontend@latest update

流程简图

业务仓根目录
    │
    ▼
npx @siyuan0215/cg-frontend init     ← 装 Pack、探测、投影 IDE 入口
    │
    ▼
/cg-frontend-init                    ← Review config → confidence: reviewed
    │
    ▼
日常 /cg-frontend（CF）写代码

Commands（CLI）

| Command | Purpose | |---------|---------| | init | 安装 Pack、探测 config、投影 IDE 入口（含 init Skill） | | install | 只同步 Pack + 入口，不重新探测 | | sync | 按 .install.json 刷新 Pack 与入口 | | update | 升 Pack、补缺 config 默认值、重投影入口 | | doctor | 检查 config / 入口 / packVersion / confidence |

全部支持 --help。

Init flags

Shared（install 同样可用）：

| Flag | Description | |------|-------------| | --global | 用户级 skills；不写业务仓 config.yaml | | --ide <ides> | cursor, qoder, claude, copilot（逗号分隔） | | --yes | 非交互：scope=project；未传 --ide 时默认 cursor,qoder |

Init-only：

| Flag | Description | |------|-------------| | --force-detect | 备份已有 config 后全量重探 | | --skip-detect | 跳过探测，只写默认 config |

无 TTY 时必须加 --yes。

Examples:

npx @siyuan0215/cg-frontend init
npx @siyuan0215/cg-frontend init --yes --ide cursor,claude
npx @siyuan0215/cg-frontend init --yes --force-detect
npx @siyuan0215/cg-frontend init --global --yes --ide cursor

Review confidence

Init / 重探后 meta.confidence 恒为 draft：

• draft： 可只读分析、小范围建议；加依赖、改目录、大重构需先问人或完成 /cg-frontend-init
• reviewed： 配置已人工确认，日常 CF Skill 按项目变量执行

meta:
  confidence: reviewed

doctor 在仍为 draft 时给出 confidence-draft 警告。CLI / Skill 绝不会自动升为 reviewed。

IDE matrix

| IDE | 入口 | Notes | |-----|------|-------| | Cursor | .cursor/skills/cg-frontend/、.cursor/skills/cg-frontend-init/ | 可用 /cg-frontend、/cg-frontend-init | | Qoder | .qoder/skills/cg-frontend/、.qoder/skills/cg-frontend-init/ | 同上 | | Claude Code | CLAUDE.md（<!-- cg-frontend:start/end -->） | 无斜杠 Skill；初始化请按 README 人工 Review，或 @ cg-frontend/skills/cg-frontend-init/SKILL.md | | GitHub Copilot | AGENTS.md + .github/copilot-instructions.md | 同上，入口为短指令块 |

未勾选的 IDE 不写文件。sync / update 只刷新 .install.json 里记录的 IDE。

Global：用户目录下的 skills + 真源缓存 ~/.siyuan0215/cg-frontend/pack。

Update and doctor

npx @siyuan0215/cg-frontend@latest update
npx @siyuan0215/cg-frontend doctor

update 不覆盖已有非空业务字段，只补 Schema 新默认值。钉版本回滚：

npx @siyuan0215/[email protected] update

Project layout（init 之后）

your-repo/
├── cg-frontend/
│   ├── config.yaml
│   ├── context.md
│   ├── SKILL.md                 # 主 Skill 正文
│   ├── skills/
│   │   └── cg-frontend-init/
│   │       └── SKILL.md         # 初始化 Skill 正文
│   └── .install.json
├── .cursor/skills/cg-frontend/
├── .cursor/skills/cg-frontend-init/   # Cursor 斜杠可调
├── .qoder/skills/cg-frontend/
├── .qoder/skills/cg-frontend-init/
├── CLAUDE.md                          # 若选了 claude
├── AGENTS.md                          # 若选了 copilot
└── .github/copilot-instructions.md

请将 cg-frontend/ 与 IDE 入口一并提交，方便同事 git pull 即用。

Publishing（maintainers）

1. npm test
2. 临时目录烟测：npx . init --yes
3. 更新 CHANGELOG.md，bump package.json version
4. commit + tag vX.Y.Z
5. npm login → npm publish --access public
6. 通知业务仓：npx @siyuan0215/[email protected] update，必要时再跑 /cg-frontend-init

npm pack --dry-run

files 白名单：bin/、src/、pack/、adapters/、README.md、CHANGELOG.md。勿提交 token / .npmrc 凭据。

Security

• 勿将 npm token 写入仓库、文档、聊天或 CI 日志
• 泄露后立即轮换再发版
• 发布物仅为公开 Skill + CLI，不含业务密钥

Requirements

• Node.js ≥ 18

License

MIT