From 26ca0e6ab2a640b8244879aaa7bb7cf8c13f3a76 Mon Sep 17 00:00:00 2001 From: zhoujie <929834232@qq.com> Date: Tue, 21 Jul 2026 02:28:34 -1000 Subject: [PATCH] =?UTF-8?q?feat(skills):=20=E6=96=B0=E5=A2=9E=20git-commit?= =?UTF-8?q?=20=E6=8A=80=E8=83=BD=E4=B8=8E=E6=A0=B9=E7=9B=AE=E5=BD=95=20CLA?= =?UTF-8?q?UDE.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增的技能把"生成规范 commit message"这套步骤固化下来(Conventional Commits 格式、提交前检查密钥/误提交的二进制文件),避免每次会话重新现编、 风格漂移。 CLAUDE.md 记录了这个技能库的目录结构、核心设计原则(反幻觉是硬约束、脚本 优先于临场编 API 调用、草稿区与交付物分离)、已知薄弱环节,以及已经和用户 确认的下一步计划(给检索脚本补测试和限流重试、新增引用一致性核查技能), 方便以后的会话不用重新推导这些上下文。 Co-Authored-By: Claude Sonnet 5 --- .claude/skills/git-commit/SKILL.md | 77 ++++++++++++++++++++++++++++++ CLAUDE.md | 70 +++++++++++++++++++++++++++ 2 files changed, 147 insertions(+) create mode 100644 .claude/skills/git-commit/SKILL.md create mode 100644 CLAUDE.md diff --git a/.claude/skills/git-commit/SKILL.md b/.claude/skills/git-commit/SKILL.md new file mode 100644 index 0000000..4b795ad --- /dev/null +++ b/.claude/skills/git-commit/SKILL.md @@ -0,0 +1,77 @@ +--- +name: git-commit +description: Generate a Conventional-Commits-style message from the repo's current staged/unstaged changes and create the commit. Use whenever the user explicitly asks to commit, save, or checkpoint their work ("提交一下", "commit这些改动", "帮我提交代码", "存一下进度", "commit this"). Never invoke this proactively — only when the user asks for a commit, not merely after finishing an edit. Does not cover pushing, PR creation, amending, or any other git operation. +--- + +# Git 提交(规范化 commit message) + +## 为什么需要这个技能 + +"提交一下"这句话背后其实有一套容易被跳过的步骤:先看清楚这次改动到底涉及 +哪些文件、有没有不该进版本库的东西(密钥、临时文件、误生成的二进制),再把 +分散的改动归纳成一句准确说明"为什么改"而不是"改了什么"的话——好的commit +message省的是未来翻`git log`时重新读一遍diff的时间。这个技能把这套步骤和 +一套固定的message格式(Conventional Commits)定下来,避免每次现编、风格漂移。 + +## 工作流程 + +### 第一步:摸清这次改动的全貌 + +并行执行: +- `git status`(不要加`-uall`,大仓库会有性能问题) +- `git diff` 看未暂存的改动,`git diff --cached` 看已暂存的改动 +- `git log --oneline -10` 看最近的提交,判断这个仓库习惯的message风格(有的仓库不用Conventional Commits前缀,这时候跟随仓库现有风格优先于本技能默认的格式) + +### 第二步:提交前检查——发现问题就先说清楚,不要直接提交 + +逐条过一遍将要暂存的文件,确认没有: +- 明显的密钥/凭据文件(`.env`、`credentials.json`、私钥等)——发现了就跳过并提醒用户,不要连带提交 +- 不该进版本库的产物:打包导出的二进制(`.zip`/`.skill`等)、编辑器/系统临时文件、体积异常大的文件 +- 用`git add -A`/`git add .`扫进来的、用户可能还不想提交的无关改动——按文件名显式`git add`,不要笼统全加 + +发现可疑内容,先列出来问用户怎么处理,不要自作主张排除或包含。 + +### 第三步:生成 commit message + +采用 Conventional Commits 格式(除非第一步发现这个仓库明显用别的风格,这种情况下跟随仓库风格): + +``` +(): + + +``` + +- `type` 从改动的实际性质里选,不要凭感觉:`feat`(新功能)、`fix`(修bug)、 + `refactor`(不改行为的重构)、`docs`(纯文档)、`test`(测试)、`chore`(构建/ + 依赖/杂项)、`style`(纯格式,不改逻辑)——一次提交只涉及一种性质就只写一个 + type;如果改动明显跨性质(比如"顺手"把无关重构也塞进了这次提交),提醒用户 + 考虑拆成多个提交,而不是硬凑一个笼统的type。 +- `scope` 可选,涉及单一模块/skill时加上(比如`literature-search-verify`、 + `paper-writing-grounded`),改动横跨全仓库时省略。 +- `subject` 祈使语气、不超过~70字符、不以句号结尾,说清楚这次改动做了什么, + 但真正的价值在于讲清楚**为什么**要这么改——如果"为什么"不是从改动本身能 + 一眼看出来的(比如修了一个不明显的bug、调整了一个非默认行为),写进body里, + 不要只重复diff里已经能看到的内容。 +- 不要在message里提及和这次改动无关的历史背景或猜测性动机。 + +### 第四步:暂存并提交 + +- 按第二步筛选后的文件列表显式`git add ...`,不要`-A`/`.` +- 用 heredoc 传message,保证多行格式正确: + ```bash + git commit -m "$(cat <<'EOF' + (): + + + EOF + )" + ``` +- 提交后跑一次`git status`确认工作区状态符合预期 + +### 第五步:红线 + +- 只在用户明确要求提交时才创建commit,不要在完成一次编辑后主动提交 +- 不新建commit时优先于`--amend`——只有用户明确要求"修改上一个commit"才用amend,而且如果上一次是因为pre-commit hook失败而"没有真正提交成功",绝不能用`--amend`(那样会改到更早的一个commit) +- 不加`--no-verify`/`--no-gpg-sign`跳过hook或签名,除非用户明确要求;hook失败时先定位问题、修复后重新`git add`再建一个新commit +- 不主动`git push`,除非用户在这次请求里明确说了要推送 +- 不做`reset --hard`/`checkout --`/`clean -f`等破坏性操作来"顺手"清理提交前发现的问题,发现了就报告给用户决定 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..1e073bf --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,70 @@ +# autoPaper — 科研辅助 Claude Skill 库 + +本仓库不是一篇具体论文的工作区,而是一套持续维护的 Claude Code skill 库, +服务于科研工作流(文献检索 → 核实 → 归档 → 写作)。`references/` 下按主题 +归档的文献是这套 skill 实际产出的样例/沉淀,不是本仓库的主体。 + +## 目录结构 + +``` +.claude/skills/ 所有 skill 的定义,每个子目录一个 skill + literature-search-verify/ 检索 + 反幻觉引用核查 + SKILL.md skill 说明(frontmatter name 必须与目录名一致) + scripts/ 纯标准库 Python 脚本,无第三方依赖 + output/ 脚本运行时草稿区,.gitignore 掉,不进版本库 + paper-writing-grounded/ 论文写作(强制数据溯源) + SKILL.md + git-commit/ 规范化 commit message 生成与提交 + SKILL.md +references// literature-search-verify 归档产出的稳定文献库 + references.bib 已验证文献,写作阶段 \cite{} 直接复用这里的 key + README.md 人可读索引,含 suspect/unverified 条目说明 + pdfs/ 开放获取的原文 PDF(如有) +``` + +## 核心设计原则(新增/修改 skill 时必须保持) + +1. **反幻觉是硬约束,不是建议**:任何进入正文引用或数字的内容都必须能独立核实 + 或追溯到真实数据,验证不通过就必须显式标记(`suspect`/`unverified`/ + `[需要数据: ...]`),绝不能为了让输出"看起来完整"而悄悄丢弃或蒙混过关。 +2. **脚本优先于临场编 API 调用**:能写成 `scripts/` 里可重复运行的脚本就不要 + 指望模型每次现场拼 HTTP 请求——后者不可复现、容易在细节上出错。脚本只用 + 标准库,不引入第三方依赖,保证任何环境下拿来就能跑。 +3. **草稿区与交付物分离**:skill 自己的 `output/` 只是运行痕迹,不是可信的最终 + 产物;确认稳定后要显式归档到 `references//` 这类项目级目录,才算数。 +4. **skill 之间通过约定(如 bibtex key)解耦协作**,而不是互相读对方内部状态; + 每个 SKILL.md 末尾应有一节说明它和其他 skill 的配合方式。 +5. **目录名必须和 SKILL.md frontmatter 里的 `name:` 完全一致**——skill 发现/ + 调用是按目录名走的,两者不一致会导致"文档里写的名字"和"实际能唤起的名字" + 对不上(曾经出现过 `paper-wiriting-grounded` 目录名手滑打错、和 frontmatter + 里正确拼写的 `paper-writing-grounded` 不一致的问题,已修正)。 + +## 已知薄弱环节 / 待办方向 + +- `scripts/search_semantic_scholar.py`、`verify_citation.py` 对 Semantic Scholar + 的限流(HTTP 429)没有重试/退避,会话量大时会导致大量条目退化成只有单源验证 + (已在 `references/uav_aeromagnetic_compensation/README.md` 的检索记录里实际发生过)。 +- 核心正确性逻辑(`verify_citation.py` 的三档判定、`archive_references.py` 的 + bib 字段解析)目前没有自动化测试兜底,只能靠人工抽查实际输出结果。 +- 目前只覆盖"检索/核实"与"写作/溯源"两段,引用一致性核查(定稿里的 + `\cite{}` 是否都对得上 `references.bib`、有没有归档了却从未引用的条目)、 + 面向具体学科的补充检索源等还没有对应 skill。 + +## 下一步计划(已和用户确认,尚未实施) + +1. **给核心脚本补单测 + 给网络请求加限流重试**:`verify_citation.py` 的三档 + 判定逻辑、`archive_references.py` 的 bib 字段解析(覆盖嵌套花括号等边界 + 情况)补 pytest 单测;`search_semantic_scholar.py` 等对 S2/arXiv/Crossref + 的请求加退避重试,避免再出现"S2 被限流导致大量条目退化成单源验证"的情况。 +2. **新增"引用一致性核查" skill**:检查定稿里所有 `\cite{}` 的 key 是否都能在 + 对应主题的 `references//references.bib` 里找到,以及有没有已归档 + 但从未被正文引用的"僵尸条目",在 literature-search-verify 和 + paper-writing-grounded 之间补上这个校验环节。 + +## 新增 skill 时的约定 + +- SKILL.md 的 frontmatter `description` 要写清楚"什么场景下必须触发这个 + skill",因为这是 skill 被自动选中的唯一依据。 +- 正文按"为什么需要 / 工作流程 / 和其他 skill 的配合"组织,和现有两个 skill + 保持同样的结构和颗粒度。 +- 目录名 = frontmatter `name`,不要有拼写差异。