diff --git a/AGENTS.md b/AGENTS.md index 6fffdea..9f852cd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,6 +53,7 @@ human would never read, stop — you have the wrong file. | Naming, comments, code style | `docs/05-code-style.md` | | Task packages, handoff checklists | `docs/06-handoff.md` | | Codex usage and AGENTS.md conventions | `docs/07-codex.md` | +| Product project spec (semver, manifest, build) | `docs/08-product-spec.md` | ## What NOT to do @@ -76,12 +77,23 @@ human would never read, stop — you have the wrong file. ## Versioning / releases -- Tags follow `YYYYMMDD` (e.g. `20260520`). Multiple tags on the same - day get a `-N` suffix (`20260520-2`). -- Annotated tags only. Tag messages summarize what changed since the - previous tag. +Two tag styles, by project type: + +- **Spec repos** (this one, other agreement docs) — date tags: + `YYYYMMDD`, with `-N` suffix for same-day reissues (`20260520-2`). + Tag from `main`. +- **Product repos** (task_assistant, authoring-tool — anything with + versioned artifacts shipped to users) — semver: `v`. Tag from + `dev`. Internal version (`0.2.4`), display version (`V0.2.4`), and + tag (`v0.2.4`) must stay in sync. See `docs/08-product-spec.md` for + the full ruleset (manifest, release-field sync list, sensitive-info + scan, minimum delivery checklist). + +Universal rules: + +- Annotated tags only. Tag messages summarize what changed. - Tags are immutable once pushed. If a tag is wrong, cut a new one. -- Tag only on `main`. +- This repo is a spec repo, so tagging here means a date tag. ## Working directory expectations diff --git a/CLAUDE.md b/CLAUDE.md index 9e71457..9764b2c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -52,6 +52,7 @@ human would never read (or vice versa), stop — you have the wrong file. | Naming, comments, code style | `docs/05-code-style.md` | | Task packages, handoff checklists | `docs/06-handoff.md` | | Codex usage and AGENTS.md conventions | `docs/07-codex.md` | +| Product project spec (semver, manifest, build) | `docs/08-product-spec.md` | ## What NOT to do @@ -75,12 +76,23 @@ human would never read (or vice versa), stop — you have the wrong file. ## Versioning / releases -- Tags follow `YYYYMMDD` (e.g. `20260520`). Multiple tags on the same - day get a `-N` suffix (`20260520-2`). -- Annotated tags only. Tag messages summarize what changed since the - previous tag. +Two tag styles, by project type: + +- **Spec repos** (this one, other agreement docs) — date tags: + `YYYYMMDD`, with `-N` suffix for same-day reissues (`20260520-2`). + Tag from `main`. +- **Product repos** (task_assistant, authoring-tool — anything with + versioned artifacts shipped to users) — semver: `v`. Tag from + `dev`. Internal version (`0.2.4`), display version (`V0.2.4`), and + tag (`v0.2.4`) must stay in sync. See `docs/08-product-spec.md` for + the full ruleset (manifest, release-field sync list, sensitive-info + scan, minimum delivery checklist). + +Universal rules: + +- Annotated tags only. Tag messages summarize what changed. - Tags are immutable once pushed. If a tag is wrong, cut a new one. -- Tag only on `main`. +- This repo is a spec repo, so tagging here means a date tag. ## Sync with AGENTS.md diff --git a/README.md b/README.md index d4abd72..ae7865f 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@ - Git 工作流(分支、commit、PR、review、tag) - Skill 管理与项目规划节奏 - 代码与产出风格(命名、注释、README、任务包、handoff) +- 产品类项目(task_assistant 这类有版本、有发行包的)的设计与发版规范 每篇都很短。一条规则要超过半页才能解释清楚的,多半还不是规则——是个待讨论项。 @@ -38,7 +39,8 @@ team-guide/ │ ├── 04-skills-and-planning.md ← skill 目录 + 规划节奏 │ ├── 05-code-style.md ← 命名、注释、结构 │ ├── 06-handoff.md ← 任务包、handoff 清单 -│ └── 07-codex.md ← Codex 使用、AGENTS.md 同步规则 +│ ├── 07-codex.md ← Codex 使用、AGENTS.md 同步规则 +│ └── 08-product-spec.md ← 产品类项目的设计与发版规范 └── templates/ ├── CLAUDE.md.template ← 给 AI 看(英文) ├── AGENTS.md.template ← 给 AI 看(英文) @@ -58,15 +60,26 @@ team-guide/ ## 版本管理 -按日期打 tag,格式 `YYYYMMDD`,比如 `20260520`。 +按**项目类型**分两种 tag 风格: -- `main` 永远是当前工作副本,随时合并。 -- 一天最多一个 tag。同一天有多次发布,用 `YYYYMMDD-N` 后缀(`20260520-2`)。 +- **规范类**(本仓库 team-guide、其他规约文档)—— 按日期: + `YYYYMMDD`,比如 `20260520`。同一天多次发布加 `-N` 后缀 + (`20260520-2`)。 +- **产品类**(task_assistant、authoring-tool 这种有版本、有发行包 + 的)—— semver:`v0.2.4`。三处版本号必须同步(内部 `0.2.4` / + 显示 `V0.2.4` / tag `v0.2.4`),细则见 + [`docs/08-product-spec.md`](docs/08-product-spec.md)。 + +通用规则: + +- `main`(规范类)/ `dev`(产品类)永远是当前工作副本,随时合并。 - Tag 一旦推到远端就不能改、不能删、不能 force-push。 - 大改写新 tag,不动旧 tag。 -- 谁要"用某一版",告诉对方 tag 名(例:`team-guide @ 20260520`)就行。 +- 谁要"用某一版",告诉对方 tag 名(例:`team-guide @ 20260520`、 + `task_assistant @ v0.2.4`)就行。 -打 tag 的具体命令和场景见 [`docs/03-git-workflow.md`](docs/03-git-workflow.md) 的 Tag 一节。 +打 tag 的具体命令和场景见 [`docs/03-git-workflow.md`](docs/03-git-workflow.md) +的 Tag 一节。 最近 tag 列表:[git.simgreek.com/simgreek/team-guide/tags](https://git.simgreek.com/simgreek/team-guide/tags) diff --git a/docs/03-git-workflow.md b/docs/03-git-workflow.md index 68b5218..0524487 100644 --- a/docs/03-git-workflow.md +++ b/docs/03-git-workflow.md @@ -72,20 +72,35 @@ Reviewer 检查清单: ## Tag(版本管理) -按日期打 tag:`YYYYMMDD`(比如 `20260520`)。每个 tag 是 `main` -某一时刻的快照——值得指着说"我们就按这版来"。 +按项目类型分两种 tag 风格: -规则: +| 项目类型 | Tag 格式 | 例子 | 用在哪儿 | +| -------- | ------------------- | -------------------------- | ------------------------------------- | +| 规范类 | `YYYYMMDD[-N]` | `20260520`、`20260520-2` | team-guide、规约文档、内部约定仓库 | +| 产品类 | `vX.Y.Z` | `v0.2.4` | task_assistant、有版本和发行包的产品 | -- 只在 `main` 上打 tag。功能分支打 tag 是 smell。 -- 一天最多一个 tag。同一天再切一个,加 `-N` 后缀:`20260520-2`、 - `20260520-3`。 +判断标准:会有"用户"拿到这个项目的版本化产物——产品类。否则——规范 +类。详细规则见 [`docs/08-product-spec.md`](08-product-spec.md)。 + +每个 tag 是 `main` 某一时刻的快照——值得指着说"我们就按这版来"。 + +通用规则(两类都适用): + +- 只在 `main`(规范类)或 `dev`(产品类)上打 tag。功能分支打 tag + 是 smell。 - 用 annotated tag,不用 lightweight。`git tag -a` 加一两句说自上次 tag 以来改了什么。 - Tag 一旦推到远端就不能改、不能删、不能 force-tag。错了就再切一个。 - Tag commit、push tag、告诉大家 tag 名字——这就是发布。 -切 tag: +规范类专属:一天最多一个 tag。同一天再切一个,加 `-N` 后缀: +`20260520-2`、`20260520-3`。 + +产品类专属:semver 三元组、产品 README 必备版本字段同步、tag +message 用 ` V`——细则见 +[`docs/08-product-spec.md`](08-product-spec.md)。 + +切 tag(规范类): ```bash git checkout main @@ -94,6 +109,15 @@ git tag -a 20260520 -m "team-guide 20260520: bilingual README, dated tags" git push origin 20260520 ``` +切 tag(产品类): + +```bash +git checkout dev +git pull --ff-only dev +git tag -a v0.2.4 HEAD -m " V0.2.4" +git push v0.2.4 +``` + 查看 / 对比: ```bash @@ -102,17 +126,20 @@ git show 20260520 # 看一个 tag 里有什么 git log --oneline 20260513..20260520 # 两个 tag 之间改了什么 ``` -什么时候切 tag: +什么时候切 tag(规范类): - 本仓库的 docs 改了,队友需要重新读。 - 加了、删了或重组了 template。 - 新的约定正式生效(不是还在讨论)。 -什么时候**不**切 tag: +什么时候**不**切 tag(规范类): - 改错别字、调格式、修死链 → 直接 push 到 `main`。 - 还在讨论的草稿 → 走 PR,不打 tag。 +产品类切 tag 跟着发版走,触发条件由[最低交付标准](08-product-spec.md#最低交付标准每次可给别人用的版本) +决定。 + ## 不要做的事 - 不要 `git push --force` 到 `main`。永远不要。push 到自己分支 diff --git a/docs/08-product-spec.md b/docs/08-product-spec.md new file mode 100644 index 0000000..619420d --- /dev/null +++ b/docs/08-product-spec.md @@ -0,0 +1,291 @@ +# 08 — 产品类项目规范 + +把 task_assistant 这类**有版本、有发行包、有用户使用**的项目从设计 +到发布要遵循的约定写下来。规范性文件(像本仓库 team-guide 自己)按 +日期 tag;产品代码按 semver。 + +## 两类项目的分界 + +| 维度 | 规范类(team-guide、规约文档) | 产品类(task_assistant、authoring-tool) | +| ---------- | ----------------------------- | ---------------------------------------- | +| 内容 | 文档、约定、模板 | 可执行代码、可发行的产物 | +| Tag 格式 | `YYYYMMDD` / `YYYYMMDD-N` | `v..` | +| 验收 | 人能读懂 | 测试通过、能跑起来 | +| 分发渠道 | Git 仓库本身 | Git(源码)+ 分发渠道(OpenList、HF 等) | +| 版本字段同步 | 没有 | 多处必须同步(见下文) | +| 用户 | 团队成员 | 真实使用者 | + +不确定一个项目是哪类,问自己:"会有'用户'拿到这个项目的版本化产物 +吗?" 会就是产品类。 + +## 版本号 + +**Semver 三元组**:`major.minor.patch`。 + +- **major** —— 不向后兼容的改动(schema 改了、CLI 参数改了、产物格式改了) +- **minor** —— 向后兼容的功能增加 +- **patch** —— bug fix、性能优化、内部重构 + +我们的项目内部用三种写法,**三处必须同步**: + +| 用途 | 格式 | 例子 | 在哪儿出现 | +| ------------ | ------------------ | ---------------- | ----------------------------------- | +| 内部版本号 | `X.Y.Z` | `0.2.4` | `package.json`、`pyproject.toml` | +| 显示版本号 | `VX.Y.Z` | `V0.2.4` | UI 胶囊、README 标题、release note | +| Git tag | `vX.Y.Z` | `v0.2.4` | Git tag 名 | + +发布时**一个不能漏**的同步检查清单(用 task_assistant 举例): + +``` +package.json "version": "0.2.4" +public/index.html version chip 初始值 +server.js fallback 版本 +scripts/build-release.js fallback 版本 + release notes +scripts/build-release-windows.js fallback 版本 + release notes +README.md 标题、版本状态段 +README.en.md 同上 +``` + +每个项目都该在 README 里列一份"发版必改的版本字段"清单,**位置写 +死**。漏一处下一版就漂移。 + +## Tag + +```bash +git tag -a v0.2.4 HEAD -m " V0.2.4" +git push v0.2.4 +``` + +规则: + +- 用 annotated tag(`-a`),不用 lightweight。 +- Tag message 用英文,格式 ` V`,跟 displayVersion + 一致。 +- 一个版本一个 tag。同版本不同平台不要分多个 tag。 +- 已经用于发行的 tag **不要移动**。错了发 patch(`v0.2.5`)覆盖。 +- 误打的 tag 在**没用于发行前**可以删: + +```bash +git tag -d v0.2.4 +git push :refs/tags/v0.2.4 +git tag -a v0.2.4 -m " V0.2.4" +git push v0.2.4 +``` + +## 分支策略 + +产品类项目至少有: + +- **`dev`** —— 默认协作分支。日常开发、bug 修复、文档更新、发行前 + 准备都进这里。 +- **功能分支** —— `/`,开 PR 合到 `dev`。 + +不留含义不清的 `master`。需要稳定分支时用明确名字,比如: + +``` +release/v0.3 +release/v0.3-hotfix +``` + +发布从 `dev` 起步——拉取 → 检查 → 改版本号 → 打 tag → 构建 → 上传。 + +## Git 与分发分家 + +**Git 管源码,分发渠道(OpenList / Hugging Face / 其他)管发行物**。 +两者职责不混。 + +进 Git: + +- 源代码、构建脚本、文档、协作规范、必要的小型静态资源、模板、 + role / 配置表。 + +不进 Git: + +``` +config/ 本地配置 +logs/ 运行日志 +feedback-records/ 用户反馈 +generated_task_packages/ 任务输出 +reports/ 验证报告 +runtime-temp/ 临时运行态 +release/ release-build/ release-dev/ release-merge/ +.venv/ __pycache__/ node_modules/ +``` + +进分发渠道(典型路径,按项目调): + +``` +//dist/ 面向使用者的发行 zip + manifest +//feedback// 用户上传的反馈 +``` + +发行 zip **必须自包含**:用户解压点击就能跑,不在用户机器上装 +依赖。具体内容随项目变,但原则不变。 + +## Manifest + +每次发布在分发渠道根目录放一份 `manifest.json`,客户端启动时读它判 +断有没有更新: + +```json +{ + "name": "", + "version": "0.2.4", + "displayVersion": "V0.2.4", + "released_at": "2026-05-18T17:00:00Z", + "platforms": { + "windows": { + "url": "/-v0.2.4-windows.zip", + "size": 123456789, + "sha256": "" + }, + "macos-arm64": { "url": "...", "size": ..., "sha256": "..." }, + "macos-x64": { "url": "...", "size": ..., "sha256": "..." } + }, + "release_notes": "" +} +``` + +上传后**重新拉一遍** manifest,肉眼对一遍 size 和 sha256 是不是新的。 +看到 size 跟旧版一致——分发渠道有缓存或上传出错。 + +## 更新机制 + +我们做的是"用户确认式更新",不是无人值守强推: + +1. 客户端启动时拉 manifest,比版本号。 +2. 有新版**提示用户**,不直接下载。 +3. 用户点同意,下载到本地。 +4. 用户点安装,重启生效。 + +任何一步不要替用户跳过。这条往后写进每个产品的 `CLAUDE.md` / +`AGENTS.md` 的"Don'ts"。 + +## 反馈与日志 + +反馈走"本地优先 + 异步上传": + +``` +本地: + feedback-records/feedback--.json + logs/-YYYY-MM-DD.jsonl + +云端(上传成功后): + //feedback//.json +``` + +规则: + +- 上传**失败不影响本地保存**。UI 提示"本地已存,上传失败可重试"。 +- 反馈和日志**必须脱敏**:API key、Bearer token、cookie、password、 + secret、私密账号——发上去之前在客户端就抹掉。 +- 排查问题时让用户走反馈页提交,**不要**让用户直接发 `config/` 或 + 完整日志目录。 + +## 敏感信息检查 + +提交前每次都做: + +```bash +git diff --cached +``` + +定期跑关键词扫描(PowerShell 例子见 task_assistant 的 +COLLABORATION_AND_RELEASE_WORKFLOW.md,bash 大致等价): + +```bash +git grep -nE "sk-|hf_|Bearer |apiKey|ANTHROPIC_API_KEY|OPENAI_API_KEY|password|secret" \ + -- ':!*.lock' ':!vendor/**' ':!**/__pycache__/**' +``` + +命中**必须人工判断**,不能照单提交,也不能照单删(注释里的 demo +key 跟真 key 都会命中)。 + +误提交真密钥的应急流程: + +1. **立刻**让对应 key/token 失效。 +2. 删除或更换本地配置。 +3. 通知协作者。 +4. 评估要不要重写 Git 历史(`git filter-repo` 或团队约定的方式)。 + +只追加一个"删除 key"的 commit 是**不够安全**的——历史里仍然能看到。 + +## 发版流程(标准动作) + +```bash +# 1. 同步 +git checkout dev +git pull --ff-only dev +git status --short --branch + +# 2. 检查 + + + +# 3. 改版本号(按本项目的"必改清单"逐项改) +# package.json、UI 胶囊、server.js、build script、README + +# 4. commit + tag +git add +git commit -m "chore: release vX.Y.Z" +git tag -a vX.Y.Z HEAD -m " VX.Y.Z" +git push dev +git push vX.Y.Z + +# 5. 构建 + + +# 6. 上传 manifest + zip 到分发渠道,验证 size/sha256 +``` + +## 产品 README 必备段落 + +每个产品类项目的 README,在通用 README 模板基础上,**额外**包含: + +- **版本状态段** —— 当前源码版本、内部版本号、协作分支、协作仓库、 + 历史迁移来源(如果有)、默认本地服务地址(如果有)、默认输出 + 目录。 +- **快速启动段** —— 按平台分(Windows / macOS / Linux),覆盖 + 解压、启动、访问、关闭。 +- **发行包内置内容清单** —— 让用户知道完整包应该有什么。 +- **发版必改字段清单** —— 给开发者的,写明哪些文件要同步改版本号。 + +人填模板见 [`templates/README.md.template`](../templates/README.md.template); +产品项目按上面清单加段落。 + +## 最低交付标准(每次"可给别人用"的版本) + +照搬 task_assistant 的清单,按项目改: + +- [ ] `/dev` 有对应 commit +- [ ] `` 有对应 tag(`v`) +- [ ] `package.json` / `pyproject.toml` 版本正确 +- [ ] UI 上版本胶囊显示正确 +- [ ] Lint / typecheck / test 全通过 +- [ ] 分发渠道 manifest 指向正确平台包 +- [ ] manifest 的 size / sha256 与实际文件一致 +- [ ] 发行包解压点击启动脚本即可运行 +- [ ] 包内**没有** API key、日志、用户反馈、生成产物、验证报告 + +任意一项没勾——不算"可给别人用"。 + +## 项目里要落地什么 + +新建产品类项目时,除了 [`docs/02-claude-code.md`](02-claude-code.md) +里的标准(`CLAUDE.md` + `AGENTS.md` + `.claude/`),还要: + +1. **`docs/COLLABORATION_AND_RELEASE_WORKFLOW.md`**(或类似名字)—— + 这份团队规范的项目特化版,包含本项目的版本字段清单、构建命令、 + 分发路径。task_assistant 那份就是范本。 +2. **`scripts/build-release.*`** —— 构建脚本,输出 zip + 更新 + `manifest.json`。 +3. **发版必改字段清单** —— 写进 `CLAUDE.md` / `AGENTS.md` 或上面那份 + workflow 里,**唯一来源**。 +4. **CHANGELOG.md** —— 一个版本一段,按 semver 顺序排,简述用户能感 + 知的改动。 + +不必落地的(YAGNI): + +- 复杂的发版编排工具(Lerna、Changesets)—— 人手够了。 +- 自动化 release notes 生成 —— commit message 够好就够用。 +- 多环境配置体系 —— 真有需要再说。