release: bump version to 0.43.0
This commit is contained in:
linkong
@@ -12,6 +12,19 @@ allowed-tools: ["Read", "Edit", "Bash", "Grep", "Glob"]
|
||||
|
||||
若 `$ARGUMENTS` 非空，则只检查指定文件/目录；否则检查所有未提交修改（`git diff HEAD`）。
|
||||
|
||||
## 节省上下文规则
|
||||
|
||||
优先用确定性的 CLI 检查缩小范围，不要一上来把完整文件或大 diff 读入上下文：
|
||||
|
||||
```bash
|
||||
git diff --name-only HEAD
|
||||
git diff --unified=0 HEAD -- <path>
|
||||
git diff --check
|
||||
rg -n "TODO|FIXME|console\.log|debugger|print\(" <changed-paths>
|
||||
```
|
||||
|
||||
只有 focused diff 不足以安全判断或修改时，才读取完整文件。
|
||||
|
||||
## 审查清单
|
||||
|
||||
按优先级检查以下问题（只报告在本次 diff 中**新增或修改**的代码里存在的问题）：
|
||||
@@ -59,8 +72,13 @@ git diff HEAD --name-only
|
||||
|
||||
### Step 2 — 逐文件阅读并分析
|
||||
|
||||
- 用 Read 工具读取完整文件（不只读 diff）
|
||||
- 对照审查清单，记录每个问题：文件名、行号、问题类型、建议修复方式
|
||||
先从 focused diff 开始：
|
||||
|
||||
```bash
|
||||
git diff --unified=0 HEAD -- <file>
|
||||
```
|
||||
|
||||
用 `rg`、`git diff --check`、编译器或 linter 输出确认确定性问题。只有需要上下文时才用 Read 读取完整文件。对照审查清单，记录每个问题：文件名、行号、问题类型、建议修复方式。
|
||||
|
||||
### Step 3 — 报告问题清单
|
||||
|
||||
@@ -95,6 +113,7 @@ git diff HEAD --name-only
|
||||
- 只改在审查清单中发现的问题，不做额外优化
|
||||
- 每次 Edit 只修改确实有问题的行，保持 diff 最小
|
||||
- 改完后用 `grep` 验证旧的坏代码已消失
|
||||
- 优先做精确补丁；只有仓库已有对应格式化流程时，才运行格式化工具
|
||||
|
||||
### Step 5 — 输出总结
|
||||
|
||||
|
||||
151
.claude/commands/docs.md
Normal file
151
.claude/commands/docs.md
Normal file
@@ -0,0 +1,151 @@
|
||||
---
|
||||
description: 分析本次 git 变更，在 docs/technical/zh/ 中新建或更新对应的技术文档
|
||||
argument-hint: 可选：指定要记录的主题，或留空自动从 git diff 推断
|
||||
allowed-tools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep"]
|
||||
---
|
||||
|
||||
# /docs — 技术文档写入工作流
|
||||
|
||||
## 目标
|
||||
|
||||
根据当前 git 变更（或用户指定主题）在 `docs/technical/zh/` 中写入或更新技术文档，记录**为什么**这样做，而不只是记录做了什么。
|
||||
|
||||
## 执行步骤
|
||||
|
||||
### Step 1 — 理解变更范围
|
||||
|
||||
```bash
|
||||
git diff HEAD --stat # 变更文件一览
|
||||
git diff HEAD --name-only # 变更文件列表
|
||||
git log --oneline -10 # 近期 commit 上下文
|
||||
```
|
||||
|
||||
若 `$ARGUMENTS` 指定了主题，优先聚焦该主题；否则从文件列表和 diff stat 推断变更主题。不要默认读取完整仓库 diff；只对决定文档主题所需的文件读取 focused diff：
|
||||
|
||||
```bash
|
||||
git diff HEAD -- <path>
|
||||
rg -n "class |def |function |export |router|@router|interface |type " <path>
|
||||
```
|
||||
|
||||
### Step 2 — 确认文档范围
|
||||
|
||||
分析变更，判断：
|
||||
|
||||
1. **应写几篇文档**：单一主题写一篇，跨领域变更可拆分（如后端性能优化 + 运维启动脚本分开写）
|
||||
2. **是新建还是更新**：检查 `docs/technical/zh/` 中是否已有相关文档
|
||||
3. **文档命名**：按 `领域-主题-副题.md` 格式，全小写，用连字符，如：
|
||||
- `backend-datasources-api-performance.md`
|
||||
- `ops-planet-sh-startup.md`
|
||||
- `earth-bgp-context.md`
|
||||
|
||||
```bash
|
||||
ls docs/technical/zh/ # 查看现有文档
|
||||
```
|
||||
|
||||
**先输出写作计划供用户确认**（若变更明确且范围小，可直接执行）：
|
||||
|
||||
```
|
||||
文档计划：
|
||||
新建：docs/technical/zh/ops-planet-sh-startup.md — planet.sh 启动性能优化
|
||||
更新：docs/technical/zh/backend-datasources-api-performance.md — 补充并行化细节
|
||||
```
|
||||
|
||||
### Step 3 — 写文档
|
||||
|
||||
遵循以下原则：
|
||||
|
||||
**记录 WHY，不只记录 WHAT**
|
||||
- 好：`将戳文件从 /tmp 移到 ~/.cache/planet/，因为 WSL 重启后 /tmp 被清空`
|
||||
- 差：`修改了 AI_PROVIDER_BUILD_STAMP_FILE 的值`
|
||||
|
||||
**必须包含的内容**：
|
||||
- 背景/问题：改动之前存在什么问题，为什么要改
|
||||
- 核心设计决策及其理由
|
||||
- 关键代码片段（用 diff 或 before/after 展示）
|
||||
- 相关文件列表
|
||||
|
||||
**格式要求**：
|
||||
- 使用 `##` 和 `###` 分级，不要超过三级
|
||||
- 代码块注明语言（python / bash / typescript / sql）
|
||||
- 表格用于对比多个选项或列出参数
|
||||
- 中文写作，技术术语保留英文原文
|
||||
- `docs/technical/zh/` 中的文档不得用英文原文占位；如果存在 `docs/technical/en/` 对应文件，禁止逐字复制成中文文件
|
||||
- 中文文档内部链接应指向 `docs/technical/zh/...`，除非明确引用英文专属文档
|
||||
|
||||
**文档结构模板**：
|
||||
|
||||
```markdown
|
||||
# 标题（说明做了什么）
|
||||
|
||||
## 背景
|
||||
|
||||
为什么要做这个改动，改动前存在什么问题。
|
||||
|
||||
## 核心变更
|
||||
|
||||
### 子主题一
|
||||
|
||||
before/after 或决策说明 + 关键代码
|
||||
|
||||
### 子主题二
|
||||
|
||||
...
|
||||
|
||||
## 相关文件
|
||||
|
||||
- `path/to/file.py` — 简短说明
|
||||
```
|
||||
|
||||
### Step 4 — 验证
|
||||
|
||||
- 读一遍写好的文档，确认逻辑清晰、代码片段无明显错误
|
||||
- 用 `rg --files` 或 `test -e` 确认文档中的文件路径在项目中真实存在，避免凭记忆判断：
|
||||
- 检查中文文档没有误复制英文版：
|
||||
|
||||
```bash
|
||||
python - <<'PY'
|
||||
from pathlib import Path
|
||||
same = []
|
||||
for en in sorted(Path("docs/technical/en").glob("*.md")):
|
||||
zh = Path("docs/technical/zh") / en.name
|
||||
if zh.exists() and en.read_text() == zh.read_text():
|
||||
same.append(en.name)
|
||||
if same:
|
||||
raise SystemExit("identical en/zh docs: " + ", ".join(same))
|
||||
print("no identical en/zh docs")
|
||||
PY
|
||||
```
|
||||
|
||||
- 检查中文文档内部链接没有继续指向无语言目录：
|
||||
|
||||
```bash
|
||||
rg -n "/home/ray/dev/linkong/planet/docs/technical/(?!zh|en)" docs/technical/zh --pcre2
|
||||
```
|
||||
|
||||
```bash
|
||||
# 对文档中提到的关键路径做快速验证
|
||||
ls <mentioned_paths>
|
||||
```
|
||||
|
||||
如需检查大量链接，优先用确定性提取：
|
||||
|
||||
```bash
|
||||
rg -n "\]\(([^)]+)\)" docs/technical/zh/<doc>.md
|
||||
```
|
||||
|
||||
### Step 5 — 完成确认
|
||||
|
||||
输出摘要：
|
||||
|
||||
```
|
||||
✓ 新建：docs/technical/zh/ops-planet-sh-startup.md（约 xxx 字）
|
||||
✓ 更新：docs/technical/zh/backend-datasources-api-performance.md
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 不要写流水账式的"改了 A、改了 B、改了 C"，要写改动背后的约束和权衡
|
||||
- 不要在文档中引用 PR 号、issue 号、或当前对话——这些会随时间失效
|
||||
- 代码片段保持简洁，只保留说明问题的关键部分，省略无关样板代码
|
||||
- 如果某个变更已有文档记录，优先在原文档中追加，而不是新建
|
||||
- 文档是给未来的开发者看的，假设读者熟悉项目但不了解这次改动的背景
|
||||
@@ -72,6 +72,8 @@ Verification
|
||||
## 执行风格
|
||||
|
||||
- 重证据，轻口头判断
|
||||
- 优先使用确定性工具证据：`rg`、`git diff --stat`、`git diff -- <path>`、测试、构建、lint、`curl`、数据库查询等能直接证明成功标准的方式
|
||||
- 不把大段命令输出粘进回复；保留在工具调用里，回复只总结关键证据
|
||||
- 重验收，轻自我感觉
|
||||
- 优先用测试、日志、产物、对比结果来证明完成
|
||||
- 对长期任务保持“未达标就继续”的节奏
|
||||
|
||||
@@ -28,6 +28,19 @@ allowed-tools: ["Read", "Edit", "Bash", "Glob", "Grep"]
|
||||
- `docs/CHANGELOG.md`
|
||||
- `docs/version-history.md`
|
||||
|
||||
## 节省上下文规则
|
||||
|
||||
发版判断应以确定性 CLI 证据为主，优先使用紧凑命令和定点读取：
|
||||
|
||||
```bash
|
||||
git status --short
|
||||
git diff --stat HEAD
|
||||
git diff --name-only HEAD
|
||||
rg -n "version|^## |^Released:|当前开发版本|current" VERSION frontend/package.json pyproject.toml docs/CHANGELOG.md docs/version-history.md
|
||||
```
|
||||
|
||||
除非需要判断某个代码变更是否属于本次发版，否则不要读取完整 diff。
|
||||
|
||||
## 执行步骤
|
||||
|
||||
### Step 1 — 环境检查
|
||||
@@ -45,7 +58,7 @@ cat VERSION # 读取当前版本
|
||||
### Step 2 — 确定发版类型与新版本号
|
||||
|
||||
- 若 `$ARGUMENTS` 提供了明确类型（`feature` / `bugfix`），直接使用
|
||||
- 否则根据当前 `git diff HEAD` 和 `git log` 推断
|
||||
- 否则根据 `git diff --stat HEAD`、`git diff --name-only HEAD`、必要的 focused diff 和 `git log` 推断
|
||||
- 计算新版本号（例：`0.26.2` → bugfix → `0.26.3`）
|
||||
- **先输出发版计划供用户确认**：
|
||||
|
||||
@@ -91,12 +104,13 @@ cat VERSION # 读取当前版本
|
||||
|
||||
针对本次变更范围做最小验证：
|
||||
|
||||
- Python 文件有修改：`python3 -m py_compile <changed_files>`
|
||||
- Frontend 文件有修改：运行项目标准检查（若无则跳过并说明）
|
||||
- Python 文件有修改：先用 `git diff --name-only HEAD -- '*.py'` 列出，再运行 `python3 -m py_compile <changed_files>`
|
||||
- Frontend 文件有修改：先用 `git diff --name-only HEAD -- frontend` 判断范围，再运行项目标准检查（若无则跳过并说明）
|
||||
- 版本号一致性检查：用 grep 确认 VERSION、package.json、pyproject.toml 中的版本号完全一致
|
||||
|
||||
```bash
|
||||
grep -h "version" VERSION frontend/package.json pyproject.toml
|
||||
cat VERSION
|
||||
rg -n "\"version\":|^version =|version = " frontend/package.json pyproject.toml uv.lock
|
||||
```
|
||||
|
||||
### Step 7 — 提交前预览
|
||||
|
||||
Reference in New Issue
Block a user