116 lines
5.5 KiB
Markdown
116 lines
5.5 KiB
Markdown
# @koko/ui 维护与开发规范(维护者)
|
|
|
|
适用对象: 在本仓库改动、发版的人与 agent。使用方规范见 [USAGE.md](./USAGE.md)。
|
|
|
|
## 1. 仓库结构
|
|
|
|
```
|
|
src/components/ui/ 官方 shadcn base-nova 组件(由 sync 脚本生成,不要手改)
|
|
src/components/extra/ 自研/封装组件(如 DatePicker),须满足准入门槛
|
|
src/hooks/ src/lib/ 官方依赖的 hooks、cn 工具
|
|
src/tokens.css 基准主题变量(Light Green, oklch)
|
|
src/shadcn-tailwind.css 内置的官方 shadcn Tailwind 基础样式
|
|
src/styles.css 总体样式入口
|
|
src/index.ts 统一导出
|
|
src/UPSTREAM.json 上游 shadcn 版本/样式记录
|
|
scripts/sync-shadcn.py 上游同步
|
|
scripts/prepublish-check.mjs 发版护栏
|
|
docs/ 本规范
|
|
```
|
|
|
|
核心边界: 本包只含「主要组件 + 总体样式」。业务逻辑、项目专属样式一律不收。
|
|
|
|
## 2. 日常改动类型
|
|
|
|
| 类型 | 做法 | 版本 |
|
|
|---|---|---|
|
|
| 修 bug / 小调整 | 改 `extra/` 或 `tokens.css` | patch |
|
|
| 风格调整(圆角、字体、阴影) | 改 `tokens.css` | minor(视觉有变化) |
|
|
| 同步上游 shadcn | 见 §3 | minor,破坏性变更为 major |
|
|
| 新增自研组件 | 先过 §4 准入,再实现 | minor |
|
|
| 删除/改名导出 | 先标记弃用一个版本再删 | major |
|
|
|
|
`src/components/ui/` 下文件由脚本覆盖,**手改会在下次同步丢失**。需要定制官方组件时: 优先改 `tokens.css`;确需改结构,在 `extra/` 做封装,不改 `ui/`。
|
|
|
|
## 3. 同步上游 shadcn
|
|
|
|
1. `npm run sync`(脚本在临时脚手架里跑官方 CLI,展开样式标记、替换图标为 lucide,再拷入 `ui/`,并更新 `UPSTREAM.json`)。
|
|
2. `git diff` 审查: 重点看 import 变化、新增依赖、被删除的导出。
|
|
3. 同步新增的依赖到 `package.json`。
|
|
4. `npm run check`(tsc)必须通过。
|
|
5. 重新生成 `src/index.ts` 导出,检查命名冲突。
|
|
6. 在预览站验证(§6)。
|
|
7. 发版(§5)。
|
|
|
|
建议节奏: 每月或遇到安全/重要修复时同步一次。上游更新不会自动流入,不同步就会落后。
|
|
|
|
## 4. 新增自研组件的准入门槛
|
|
|
|
**硬性条件: 该组件已被至少两个不同项目实际使用,才可以考虑放入公共库。**
|
|
|
|
流程:
|
|
|
|
1. 第一个项目需要时,在**该项目内**实现(`src/components/local/`),不进公共库。
|
|
2. 第二个项目出现同样需求,两边实现趋同后,才提出收录。
|
|
3. 收录前逐项确认:
|
|
- [ ] 两个项目都已有在用实现,并能指出具体文件位置。「预计以后会用」「看起来通用」不算。
|
|
- [ ] 官方 shadcn 没有现成等价组件(有则直接用官方)。
|
|
- [ ] 与业务无关: 无项目名、无数据请求、无业务文案、无硬编码接口。
|
|
- [ ] 由现有公共组件和 token 组合而成,样式只用 token 类,不写死颜色/像素。
|
|
- [ ] API 以两个项目的共同需求为准,不为想象中的第三方场景加参数。
|
|
- [ ] 新增依赖尽量为零;若必须新增,单独说明体积与理由。
|
|
4. 收录后:
|
|
- 放 `src/components/extra/`,在 `index.ts` 导出。
|
|
- 预览站补一个示例。
|
|
- 两个来源项目随即改为使用公共版本并删除本地实现,避免两份并存。
|
|
- 在 CHANGELOG 记录来源项目。
|
|
|
|
不满足门槛的诉求一律留在项目内。门槛对 agent 同样有效,不得绕过。
|
|
|
|
## 5. 发版
|
|
|
|
```
|
|
cd /opt/data/workspace/koko-ui
|
|
npm run check
|
|
npm version patch|minor|major --no-git-tag-version
|
|
node scripts/prepublish-check.mjs
|
|
npm pack --dry-run # 肉眼看文件清单
|
|
npm publish # token 由环境注入,见下
|
|
git add -A && git commit -m "release x.y.z" && git push origin main
|
|
```
|
|
|
|
- token 在 `/opt/data/git/gitea_token.json`(需 `write:package`),只通过临时 userconfig 注入,发完删除。禁止写进仓库、聊天或日志。
|
|
- 同名同版本不可重发。撤回: `DELETE /api/v1/packages/koko/npm/%40koko%2Fui/<ver>`。
|
|
- 发版后用不带 token 的环境 `npm view @koko/ui version` 验证。
|
|
|
|
### 发版安全护栏(必须)
|
|
|
|
包发布后匿名可读,发布前必须保证无敏感信息、体积合理。
|
|
|
|
- `prepublishOnly` 自动跑 `scripts/prepublish-check.mjs`,检查:
|
|
- 文件白名单: `package.json`、`README.md`、`src/**/*.{ts,tsx,css}`、`src/UPSTREAM.json`。
|
|
- 敏感信息: 私钥、各类 token 格式、`_authToken` 明文、硬编码凭证、JWT、URL 内嵌密码。
|
|
- 体积上限: 打包 ≤150KB、解压 ≤600KB、文件 ≤80。
|
|
- 当前基线(0.2.0): 60 文件 / 打包 39.8KB / 解压 210KB。明显偏离(如翻倍)先查原因,不要直接调高阈值。
|
|
- 禁止进入包的内容: `.env`、截图、`node_modules`、业务数据、`docs/`、`scripts/`。
|
|
- 护栏拦截时先判断是误报还是真问题,不得为通过而绕过检查。
|
|
|
|
## 6. 验证
|
|
|
|
- `npm run check` 通过。
|
|
- 预览站: `/opt/data/workspace/koko-ui-preview`(Astro),用 `npm pack` 的 tgz 安装本包后构建。
|
|
- 部署到 Netlify koko-preview,在 mac-C 浏览器验证: 控制台无报错,图表有 SVG 输出,弹窗/日期选择可用,亮/暗色各看。
|
|
- 不要在 Hermes 主机启动浏览器。
|
|
- 禁用 `file:` / `npm link`(React 双实例)。
|
|
|
|
## 7. 通知使用方
|
|
|
|
- 发版后各项目按需执行 `npm i @koko/ui@latest`,构建验证后部署。
|
|
- major 版本或有破坏性变更时,在 CHANGELOG 写迁移说明。
|
|
- 项目提出的风格诉求、缺陷汇总到本仓库处理,不接受「在项目里先打补丁」。
|
|
|
|
## 8. 凭据卫生
|
|
|
|
- 本仓库公开,任何文档与提交不得包含 token。
|
|
- 发现 token 曾在聊天或日志出现,到 Gitea「设置 → 应用」吊销并重新生成。
|