Author SHA1 Message Date
阿白叔andClaude Opus 4.7 dfa84743f9 docs: add product project spec, distinguish date vs semver tags
Distill task_assistant's COLLABORATION_AND_RELEASE_WORKFLOW into a
team-wide product project spec and clarify when each tag style applies.

- Add docs/08-product-spec.md: semver triplet (internal/display/tag),
  manifest schema, dist-channel separation, user-confirmed update
  flow, feedback/log handling, sensitive-info scan, release flow,
  minimum delivery checklist
- docs/03-git-workflow.md: split tagging into spec (YYYYMMDD) vs
  product (vX.Y.Z) sections, link to 08
- README.md, CLAUDE.md, AGENTS.md: update versioning section and doc
  index to reference 08

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 14:45:28 +08:00
5 changed files with 380 additions and 25 deletions

No files matched your search

+17 -5
View File
@@ -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<x.y.z>`. 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
+17 -5
View File
@@ -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<x.y.z>`. 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
+19 -6
View File
@@ -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)
+36 -9
View File
@@ -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 用 `<Project> V<x.y.z>`——细则见
[`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 <remote> dev
git tag -a v0.2.4 HEAD -m "<Project> V0.2.4"
git push <remote> 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 到自己分支
+291
View File
@@ -0,0 +1,291 @@
# 08 — 产品类项目规范
把 task_assistant 这类**有版本、有发行包、有用户使用**的项目从设计
到发布要遵循的约定写下来。规范性文件(像本仓库 team-guide 自己)按
日期 tag;产品代码按 semver。
## 两类项目的分界
| 维度 | 规范类(team-guide、规约文档) | 产品类(task_assistant、authoring-tool) |
| ---------- | ----------------------------- | ---------------------------------------- |
| 内容 | 文档、约定、模板 | 可执行代码、可发行的产物 |
| Tag 格式 | `YYYYMMDD` / `YYYYMMDD-N` | `v<major>.<minor>.<patch>` |
| 验收 | 人能读懂 | 测试通过、能跑起来 |
| 分发渠道 | 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 "<project-name> V0.2.4"
git push <remote> v0.2.4
```
规则:
- 用 annotated tag(`-a`),不用 lightweight。
- Tag message 用英文,格式 `<Project Name> V<x.y.z>`,跟 displayVersion
一致。
- 一个版本一个 tag。同版本不同平台不要分多个 tag。
- 已经用于发行的 tag **不要移动**。错了发 patch(`v0.2.5`)覆盖。
- 误打的 tag 在**没用于发行前**可以删:
```bash
git tag -d v0.2.4
git push <remote> :refs/tags/v0.2.4
git tag -a v0.2.4 <correct-sha> -m "<Project> V0.2.4"
git push <remote> v0.2.4
```
## 分支策略
产品类项目至少有:
- **`dev`** —— 默认协作分支。日常开发、bug 修复、文档更新、发行前
准备都进这里。
- **功能分支** —— `<owner>/<slug>`,开 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/
```
进分发渠道(典型路径,按项目调):
```
/<project>/dist/ 面向使用者的发行 zip + manifest
/<project>/feedback/<machine-id>/ 用户上传的反馈
```
发行 zip **必须自包含**:用户解压点击就能跑,不在用户机器上装
依赖。具体内容随项目变,但原则不变。
## Manifest
每次发布在分发渠道根目录放一份 `manifest.json`,客户端启动时读它判
断有没有更新:
```json
{
"name": "<project-name>",
"version": "0.2.4",
"displayVersion": "V0.2.4",
"released_at": "2026-05-18T17:00:00Z",
"platforms": {
"windows": {
"url": "<dist-url>/<project>-v0.2.4-windows.zip",
"size": 123456789,
"sha256": "<hex>"
},
"macos-arm64": { "url": "...", "size": ..., "sha256": "..." },
"macos-x64": { "url": "...", "size": ..., "sha256": "..." }
},
"release_notes": "<short markdown>"
}
```
上传后**重新拉一遍** manifest,肉眼对一遍 size 和 sha256 是不是新的。
看到 size 跟旧版一致——分发渠道有缓存或上传出错。
## 更新机制
我们做的是"用户确认式更新",不是无人值守强推:
1. 客户端启动时拉 manifest,比版本号。
2. 有新版**提示用户**,不直接下载。
3. 用户点同意,下载到本地。
4. 用户点安装,重启生效。
任何一步不要替用户跳过。这条往后写进每个产品的 `CLAUDE.md` /
`AGENTS.md` 的"Don'ts"。
## 反馈与日志
反馈走"本地优先 + 异步上传":
```
本地:
feedback-records/feedback-<timestamp>-<id>.json
logs/<project>-YYYY-MM-DD.jsonl
云端(上传成功后):
/<project>/feedback/<machine-id>/<feedback-file>.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 <remote> dev
git status --short --branch
# 2. 检查
<lint command>
<test command>
# 3. 改版本号(按本项目的"必改清单"逐项改)
# package.json、UI 胶囊、server.js、build script、README
# 4. commit + tag
git add <files>
git commit -m "chore: release vX.Y.Z"
git tag -a vX.Y.Z HEAD -m "<Project> VX.Y.Z"
git push <remote> dev
git push <remote> vX.Y.Z
# 5. 构建
<build command>
# 6. 上传 manifest + zip 到分发渠道,验证 size/sha256
```
## 产品 README 必备段落
每个产品类项目的 README,在通用 README 模板基础上,**额外**包含:
- **版本状态段** —— 当前源码版本、内部版本号、协作分支、协作仓库、
历史迁移来源(如果有)、默认本地服务地址(如果有)、默认输出
目录。
- **快速启动段** —— 按平台分(Windows / macOS / Linux),覆盖
解压、启动、访问、关闭。
- **发行包内置内容清单** —— 让用户知道完整包应该有什么。
- **发版必改字段清单** —— 给开发者的,写明哪些文件要同步改版本号。
人填模板见 [`templates/README.md.template`](../templates/README.md.template);
产品项目按上面清单加段落。
## 最低交付标准(每次"可给别人用"的版本)
照搬 task_assistant 的清单,按项目改:
- [ ] `<remote>/dev` 有对应 commit
- [ ] `<remote>` 有对应 tag(`v<x.y.z>`)
- [ ] `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 够好就够用。
- 多环境配置体系 —— 真有需要再说。