# @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「设置 → 应用」吊销并重新生成。