linkong/planet

Fork 0

Files

linkong ac69d5d354 release: bump version to 0.43.0

2026-04-28 16:10:17 +08:00

4.7 KiB

Raw Blame History

description, argument-hint, allowed-tools

description

argument-hint

allowed-tools

分析本次 git 变更，在 docs/technical/zh/ 中新建或更新对应的技术文档

可选：指定要记录的主题，或留空自动从 git diff 推断

Read

Edit

Write

Bash

Glob

Grep

/docs — 技术文档写入工作流

目标

根据当前 git 变更（或用户指定主题）在 docs/technical/zh/ 中写入或更新技术文档，记录为什么这样做，而不只是记录做了什么。

执行步骤

Step 1 — 理解变更范围

git diff HEAD --stat          # 变更文件一览
git diff HEAD --name-only     # 变更文件列表
git log --oneline -10         # 近期 commit 上下文

若 $ARGUMENTS 指定了主题，优先聚焦该主题；否则从文件列表和 diff stat 推断变更主题。不要默认读取完整仓库 diff；只对决定文档主题所需的文件读取 focused diff：

git diff HEAD -- <path>
rg -n "class |def |function |export |router|@router|interface |type " <path>

Step 2 — 确认文档范围

分析变更，判断：

应写几篇文档：单一主题写一篇，跨领域变更可拆分（如后端性能优化 + 运维启动脚本分开写）
是新建还是更新：检查 docs/technical/zh/ 中是否已有相关文档
文档命名：按 领域-主题-副题.md 格式，全小写，用连字符，如：
- backend-datasources-api-performance.md
- ops-planet-sh-startup.md
- earth-bgp-context.md

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/...，除非明确引用英文专属文档

文档结构模板：

# 标题（说明做了什么）

## 背景

为什么要做这个改动，改动前存在什么问题。

## 核心变更

### 子主题一

before/after 或决策说明 + 关键代码

### 子主题二

...

## 相关文件

- `path/to/file.py` — 简短说明

Step 4 — 验证

读一遍写好的文档，确认逻辑清晰、代码片段无明显错误
用 rg --files 或 test -e 确认文档中的文件路径在项目中真实存在，避免凭记忆判断：
检查中文文档没有误复制英文版：

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

检查中文文档内部链接没有继续指向无语言目录：

rg -n "/home/ray/dev/linkong/planet/docs/technical/(?!zh|en)" docs/technical/zh --pcre2

# 对文档中提到的关键路径做快速验证
ls <mentioned_paths>

如需检查大量链接，优先用确定性提取：

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 号、或当前对话——这些会随时间失效
代码片段保持简洁，只保留说明问题的关键部分，省略无关样板代码
如果某个变更已有文档记录，优先在原文档中追加，而不是新建
文档是给未来的开发者看的，假设读者熟悉项目但不了解这次改动的背景

4.7 KiB Raw Blame History Unescape Escape