commit 480f5c321d7de4b7459f6ff13d7e33a5af3f8616 Author: shenyuxiang Date: Sat Aug 15 23:24:17 2026 +0800 feat: add reusable engineering skill collection diff --git a/.agents/skills/add-code-comments/SKILL.md b/.agents/skills/add-code-comments/SKILL.md new file mode 100644 index 0000000..0d20f55 --- /dev/null +++ b/.agents/skills/add-code-comments/SKILL.md @@ -0,0 +1,64 @@ +--- +name: add-code-comments +description: "为用户指定的代码补充简洁、准确的变量和函数注释，并整理局部多余空行。适用于支持 // 注释的语言，仅在用户显式调用 $add-code-comments 时使用。" +--- + +# 补充代码注释 + +为用户指定的函数、类、文件或目录补充有价值的代码注释，使代码更容易阅读。 + +只允许修改注释和空白格式，不得改变代码行为。 + +## 执行范围 + +1. 读取当前目录适用的 `AGENTS.md` 和项目规则。 +2. 只处理用户明确指定的文件、函数、类或目录。 +3. 如果用户没有指定处理范围，先询问，不要默认扫描整个项目。 +4. 处理目录或整个项目时，跳过： + - 第三方依赖； + - 自动生成文件； + - 编译产物； + - 缓存、日志和临时文件； + - 包含 `auto-generated`、`generated code` 等标记的文件。 + +本 Skill 主要用于 C、C++、C#、Java、JavaScript、TypeScript 等支持 `//` 注释的语言。 + +如果目标语言不支持 `//` 注释，不得添加无效语法，应先向用户说明。 + +## 理解代码 + +添加注释前，先理解相关代码的真实作用。 + +必要时可以只读检查： + +- 变量的赋值位置和使用位置； +- 函数的调用者； +- 参数的来源； +- 返回值的用途； +- 相关配置、接口和测试； +- 单位、坐标系、状态含义和边界条件。 + +无法从代码或现有资料确认的信息不要猜测，也不要为了增加注释数量而编造说明。 + +## 注释原则 + +注释应解释代码中不能直接看出的信息，例如： + +- 变量的业务含义； +- 缩写的完整含义； +- 数值的单位； +- 坐标系和方向约定； +- 状态值或标志位的含义； +- 函数的主要目的； +- 不明显的输入输出约束； +- 算法采用这种写法的原因； +- 容易误用的边界条件； +- 重要副作用。 + +不要简单地把代码翻译成中文。 + +错误示例： + +```csharp +count++; // count 加一 +``` diff --git a/.agents/skills/add-code-comments/agents/openai.yaml b/.agents/skills/add-code-comments/agents/openai.yaml new file mode 100644 index 0000000..71ec4ba --- /dev/null +++ b/.agents/skills/add-code-comments/agents/openai.yaml @@ -0,0 +1,8 @@ + +interface: + display_name: "补充代码注释" + short_description: "为指定代码补充简洁注释并整理方法内部多余空行" + default_prompt: "使用 $add-code-comments 为我指定的代码补充准确、简洁的中文注释，并整理局部多余空行。" + +policy: + allow_implicit_invocation: false \ No newline at end of file diff --git a/.agents/skills/commit/SKILL.md b/.agents/skills/commit/SKILL.md new file mode 100644 index 0000000..35ef191 --- /dev/null +++ b/.agents/skills/commit/SKILL.md @@ -0,0 +1,35 @@ +--- +name: commit +description: "检查 Git 仓库的当前改动，生成符合仓库风格的提交信息，完成暂存、提交和推送。仅在用户显式调用 $commit 时使用。" +--- + +# 提交 Git 改动 + +安全地检查、提交并推送当前项目的 Git 改动。 + +## 定位仓库 + +1. 如果用户指定了项目路径，优先使用该路径。 +2. 否则从当前工作目录执行 `git rev-parse --show-toplevel`。 +3. 如果当前目录不是 Git 仓库，在当前工作区内浅层查找 `.git`： + - 只找到一个仓库时，使用该仓库。 + - 找到多个仓库时，列出仓库并让用户选择。 + - 没有找到仓库时，停止执行。 +4. 记录仓库根目录，后续所有 Git 命令都针对该目录执行。 +5. 读取该仓库适用的 `AGENTS.md`。 + +不要根据文件夹名称猜测仓库位置。 + +## 检查改动 + +执行并分析： + +```bash +git status --short +git diff --stat +git diff +git diff --cached +git log --oneline -8 +git branch --show-current +git remote -v +``` diff --git a/.agents/skills/commit/agents/openai.yaml b/.agents/skills/commit/agents/openai.yaml new file mode 100644 index 0000000..c03298b --- /dev/null +++ b/.agents/skills/commit/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "提交 Git 改动" + short_description: "检查当前仓库改动，生成提交信息并安全完成提交和推送" + default_prompt: "使用 $commit 检查当前项目的 Git 改动，生成合适的提交信息并提交推送。" + +policy: + allow_implicit_invocation: false \ No newline at end of file diff --git a/.agents/skills/generate-latex-document/SKILL.md b/.agents/skills/generate-latex-document/SKILL.md new file mode 100644 index 0000000..a3a9d5d --- /dev/null +++ b/.agents/skills/generate-latex-document/SKILL.md @@ -0,0 +1,70 @@ +--- +name: generate-latex-document +description: "使用内置 LaTeX 模板，将 Markdown、TXT 等零散资料整理成技术文档，或者分析代码库生成结构化代码说明文档。仅在用户显式调用 $generate-latex-document 时使用。" +--- + +# 生成 LaTeX 技术文档 + +使用 Skill 内置模板生成完整、独立、可直接上传 Overleaf 的 `.tex` 文档。 + +## 确定工作模式 + +根据用户请求选择一种模式： + +- 笔记整理模式：处理 Markdown、TXT、会议记录、学习笔记和其他零散资料。 +- 代码库说明模式：分析项目代码，生成模块、文件、类、函数和接口说明。 + +如果无法判断模式，先询问用户。 + +选择模式后只读取对应工作流： + +- 笔记整理模式：读取 `references/notes-workflow.md`。 +- 代码库说明模式：读取 `references/codebase-workflow.md`。 + +不要同时读取两个工作流，除非用户明确要求混合生成。 + +## 使用模板 + +读取 `assets/document-template.tex`，复制为新的输出文件，不修改原始模板。 + +替换以下占位符： + +- `CODEXDOCUMENTTITLE`：文档标题； +- `CODEXDOCUMENTSUBTITLE`：文档副标题； +- `CODEXPROJECTNAME`：项目或主题名称； +- `CODEXDOCUMENTAUTHOR`：作者； +- `CODEXDOCUMENTVERSION`：文档版本； +- `CODEXDOCUMENTDESCRIPTION`：封面简介； +- `CODEXDOCUMENTBODY`：完整正文。 + +如果用户没有提供作者，使用“项目组”或沿用已有文档作者，不得猜测真实姓名。 + +如果用户没有提供版本，首次生成使用 `v1.0`；更新已有文档时沿用原版本，除非用户要求修改。 + +## 输出要求 + +只生成完整的 `.tex` 文件，不生成 PDF。 + +不调用本地 LaTeX、XeLaTeX、latexmk 或其他编译工具，也不检查本地是否安装 LaTeX。 + +输出文件必须： + +- 包含完整导言区、封面、目录、正文和 `\end{document}`； +- 能够独立上传 Overleaf； +- 不依赖 Skill 目录中的模板； +- 不保留任何 `CODEX...` 占位符； +- 不保留 `XXXX`、示例数据或无意义空章节； +- 默认适配 Overleaf 的 XeLaTeX 编译器； +- 保留模板的主要视觉风格。 + +默认不要使用外部 `.sty`、`\input{}` 或 `\include{}`。 + +如果文档需要图片，可以使用相对路径，并报告需要同时上传的图片文件。 + +## LaTeX 内容规则 + +正确处理 LaTeX 特殊字符： + +```text +% _ & # $ { } ~ ^ \ +``` diff --git a/.agents/skills/generate-latex-document/agents/openai.yaml b/.agents/skills/generate-latex-document/agents/openai.yaml new file mode 100644 index 0000000..729edfa --- /dev/null +++ b/.agents/skills/generate-latex-document/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "生成 LaTeX 技术文档" + short_description: "使用内置模板整理笔记或生成结构化代码库说明文档" + default_prompt: "使用 $generate-latex-document 根据输入资料或当前代码库生成完整的 LaTeX 技术文档。" + +policy: + allow_implicit_invocation: false \ No newline at end of file diff --git a/.agents/skills/generate-latex-document/assets/document-template.tex b/.agents/skills/generate-latex-document/assets/document-template.tex new file mode 100644 index 0000000..14f3fd9 --- /dev/null +++ b/.agents/skills/generate-latex-document/assets/document-template.tex @@ -0,0 +1,318 @@ + +\documentclass[12pt,a4paper]{article} + +% ============================================================ +% 中文技术文档模板 +% 建议在 Overleaf 中使用 XeLaTeX 编译 +% ============================================================ + +\usepackage[UTF8]{ctex} +\usepackage[margin=2.5cm]{geometry} +\usepackage{titlesec} +\usepackage{fancyhdr} +\usepackage{listings} +\usepackage{xcolor} +\usepackage{graphicx} +\usepackage{amsmath} +\usepackage{amssymb} +\usepackage{booktabs} +\usepackage{longtable} +\usepackage{tabularx} +\usepackage{array} +\usepackage{enumitem} +\usepackage{tcolorbox} +\usepackage{setspace} +\usepackage{url} +\usepackage{hyperref} + +\tcbuselibrary{skins,breakable} + +% ============================================================ +% 页面设置 +% ============================================================ + +\geometry{ + a4paper, + left=2.5cm, + right=2.5cm, + top=2.5cm, + bottom=2.5cm +} + +\onehalfspacing +\setlength{\parindent}{2em} +\setlength{\parskip}{0.3em} +\setlength{\emergencystretch}{2em} + +\setlist[itemize]{ + itemsep=0.2em, + topsep=0.4em +} + +\setlist[enumerate]{ + itemsep=0.2em, + topsep=0.4em +} + +\setcounter{tocdepth}{2} +\setcounter{secnumdepth}{3} + +% ============================================================ +% 文档信息占位符 +% ============================================================ + +\newcommand{\doctitle}{CODEXDOCUMENTTITLE} +\newcommand{\docsubtitle}{CODEXDOCUMENTSUBTITLE} +\newcommand{\projectname}{CODEXPROJECTNAME} +\newcommand{\docauthor}{CODEXDOCUMENTAUTHOR} +\newcommand{\docversion}{CODEXDOCUMENTVERSION} +\newcommand{\docdescription}{CODEXDOCUMENTDESCRIPTION} + +% ============================================================ +% 颜色 +% ============================================================ + +\definecolor{primaryblue}{RGB}{35,85,145} +\definecolor{secondaryblue}{RGB}{65,105,170} +\definecolor{codebg}{RGB}{247,248,250} +\definecolor{codeframe}{RGB}{205,210,218} +\definecolor{codegreen}{RGB}{40,130,80} +\definecolor{codegray}{RGB}{110,115,125} +\definecolor{codepurple}{RGB}{145,70,165} +\definecolor{warningorange}{RGB}{210,125,30} +\definecolor{softgray}{RGB}{245,245,245} + +% ============================================================ +% 页眉页脚 +% ============================================================ + +\pagestyle{fancy} +\fancyhf{} +\fancyhead[L]{\small\doctitle} +\fancyhead[R]{\small\leftmark} +\fancyfoot[C]{\thepage} +\renewcommand{\headrulewidth}{0.4pt} +\renewcommand{\footrulewidth}{0pt} + +% ============================================================ +% 标题格式 +% ============================================================ + +\titleformat{\section} + {\Large\bfseries\color{primaryblue}} + {\thesection} + {1em} + {} + [\titlerule] + +\titleformat{\subsection} + {\large\bfseries\color{secondaryblue}} + {\thesubsection} + {1em} + {} + +\titleformat{\subsubsection} + {\normalsize\bfseries} + {\thesubsubsection} + {1em} + {} + +% ============================================================ +% 表格 +% ============================================================ + +\newcolumntype{Y}{>{\raggedright\arraybackslash}X} +\renewcommand{\arraystretch}{1.25} + +% ============================================================ +% 代码样式 +% ============================================================ + +\lstdefinestyle{codestyle}{ + backgroundcolor=\color{codebg}, + commentstyle=\color{codegreen}, + keywordstyle=\color{primaryblue}\bfseries, + numberstyle=\tiny\color{codegray}, + stringstyle=\color{codepurple}, + basicstyle=\ttfamily\footnotesize, + breakatwhitespace=false, + breaklines=true, + captionpos=b, + keepspaces=true, + numbers=left, + numbersep=8pt, + showspaces=false, + showstringspaces=false, + showtabs=false, + tabsize=4, + frame=single, + rulecolor=\color{codeframe}, + columns=fullflexible +} + +\lstdefinestyle{commandstyle}{ + backgroundcolor=\color{codebg}, + basicstyle=\ttfamily\footnotesize, + breaklines=true, + frame=single, + rulecolor=\color{codeframe}, + numbers=none, + columns=fullflexible +} + +\lstdefinelanguage{json}{ + basicstyle=\ttfamily\footnotesize, + string=[s]{"}{"}, + stringstyle=\color{codepurple}, + comment=[l]{//}, + commentstyle=\color{codegreen}, + keywords={true,false,null}, + keywordstyle=\color{primaryblue}\bfseries +} + +\lstset{style=codestyle} + +% ============================================================ +% 信息框 +% ============================================================ + +\newtcolorbox{infobox}[2][]{ + enhanced, + breakable, + colback=blue!4!white, + colframe=primaryblue, + fonttitle=\bfseries, + title={#2}, + #1 +} + +\newtcolorbox{warningbox}[2][]{ + enhanced, + breakable, + colback=orange!5!white, + colframe=warningorange, + fonttitle=\bfseries, + title={#2}, + #1 +} + +\newtcolorbox{filebox}[2][]{ + enhanced, + breakable, + colback=softgray, + colframe=gray!65!black, + fonttitle=\bfseries\ttfamily, + title={文件：#2}, + #1 +} + +\newtcolorbox{functionbox}[2][]{ + enhanced, + breakable, + colback=blue!2!white, + colframe=secondaryblue, + fonttitle=\bfseries\ttfamily, + title={函数：#2}, + #1 +} + +\newtcolorbox{qabox}[2][]{ + enhanced, + breakable, + colback=blue!4!white, + colframe=primaryblue, + fonttitle=\bfseries, + title={问题：#2}, + #1 +} + +\newtcolorbox{answerbox}[1][]{ + enhanced, + breakable, + colback=green!4!white, + colframe=green!55!black, + leftrule=4pt, + #1 +} + +% ============================================================ +% 行内代码 +% ============================================================ + +\newcommand{\code}[1]{\texttt{\detokenize{#1}}} + +% ============================================================ +% 超链接 +% ============================================================ + +\hypersetup{ + colorlinks=true, + linkcolor=primaryblue, + urlcolor=primaryblue, + citecolor=green!50!black, + bookmarks=true, + bookmarksnumbered=true, + pdftitle={\doctitle}, + pdfauthor={\docauthor} +} + +% ============================================================ +% 文档正文 +% ============================================================ + +\begin{document} + +% ============================================================ +% 封面 +% ============================================================ + +\begin{titlepage} + \centering + \vspace*{2.8cm} + + {\Huge\bfseries\color{primaryblue}\doctitle\par} + + \vspace{0.7cm} + + {\Large\docsubtitle\par} + + \vspace{2cm} + + \rule{\linewidth}{0.6mm} + + \vspace{1cm} + + \begin{tabular}{rl} + \textbf{项目或主题：} & \projectname \\[0.6em] + \textbf{作者：} & \docauthor \\[0.6em] + \textbf{日期：} & \today \\[0.6em] + \textbf{版本：} & \docversion + \end{tabular} + + \vspace{1cm} + + \rule{\linewidth}{0.6mm} + + \vfill + + \begin{minipage}{0.85\textwidth} + \centering + \small + \docdescription + \end{minipage} +\end{titlepage} + +% ============================================================ +% 目录 +% ============================================================ + +\tableofcontents +\newpage + +% ============================================================ +% 正文占位符 +% ============================================================ + +CODEXDOCUMENTBODY + +\end{document} \ No newline at end of file diff --git a/.agents/skills/generate-latex-document/references/codebase-workflow.md b/.agents/skills/generate-latex-document/references/codebase-workflow.md new file mode 100644 index 0000000..1bd75bd --- /dev/null +++ b/.agents/skills/generate-latex-document/references/codebase-workflow.md @@ -0,0 +1,107 @@ + +# 代码库说明工作流 + +分析代码库并生成面向开发、维护和使用人员的 LaTeX 代码参考文档。 + +## 定位代码库 + +如果用户指定了项目路径，优先使用该路径。 + +否则从当前目录识别 Git 仓库根目录。 + +如果当前目录不是 Git 仓库： + +1. 在工作区内浅层查找 Git 仓库； +2. 只有一个仓库时使用该仓库； +3. 存在多个仓库时让用户选择； +4. 没有仓库时，将当前项目目录作为目标。 + +读取项目适用的 `AGENTS.md`、README 和主要设计文档。 + +## 确定分析范围 + +支持两种范围： + +### `scope=core` + +默认模式，只整理： + +- 项目入口； +- 核心模块； +- 公共接口； +- 主要类； +- 关键算法； +- 外部可调用函数； +- 重要配置和数据结构。 + +不详细记录普通私有辅助函数、生成代码和测试辅助代码。 + +### `scope=all` + +只有用户明确要求时使用，尽量整理全部可识别的代码文件、类和函数。 + +如果项目规模很大，应先统计文件和符号数量，并让用户选择模块或分批生成，不要一次读取整个大型代码库。 + +## 调研代码库 + +优先检查： + +- README 和主要文档； +- 项目清单和依赖配置； +- 项目入口； +- 源码目录； +- 核心模块； +- 公共头文件和接口； +- 配置文件和配置类； +- 测试中体现的实际行为； +- Git 当前状态和最近相关提交。 + +使用 `rg --files` 和针对性符号搜索。 + +默认排除： + +- `.git`； +- `bin`、`obj`、`build`、`dist`； +- 第三方依赖目录； +- 日志、缓存和编译产物； +- 自动生成代码； +- 大型数据文件； +- 与目标模块无关的参考项目。 + +## 识别项目结构 + +根据实际代码识别： + +- 编程语言和技术栈； +- 项目入口； +- 目录职责； +- 模块边界； +- 核心数据结构； +- 模块依赖； +- 主要调用流程； +- 外部接口； +- 配置方式； +- 构建、运行和测试方法。 + +不要根据目录名或常见框架习惯编造系统行为。 + +## 组织代码文档 + +建议采用以下结构： + +```text +文档概述 +项目简介 +技术栈与运行环境 +目录结构 +总体架构 +主要运行流程 +模块说明 +文件说明 +类与数据结构 +函数与接口参考 +配置参数 +构建、运行与测试 +常见问题 +已知限制 +``` diff --git a/.agents/skills/generate-latex-document/references/notes-workflow.md b/.agents/skills/generate-latex-document/references/notes-workflow.md new file mode 100644 index 0000000..0899acd --- /dev/null +++ b/.agents/skills/generate-latex-document/references/notes-workflow.md @@ -0,0 +1,54 @@ +# 笔记整理工作流 + +把 Markdown、TXT、会议记录、学习笔记和其他零散资料整理成结构化 LaTeX 文档。 + +## 确认输入 + +优先使用用户指定的文件或目录。 + +如果用户没有明确指定输入： + +1. 检查当前任务中提到的 Markdown 和 TXT 文件； +2. 如果只有少量明显相关的文件，列出并使用； +3. 如果文件较多、主题不同或范围不明确，让用户选择； +4. 不默认读取整个工作区。 + +记录实际读取的文件，不能只根据文件名猜测内容。 + +## 分析内容 + +提取并区分： + +- 主题和目标； +- 背景信息； +- 核心概念； +- 操作步骤； +- 技术结论； +- 问题和解决方法； +- 决策和原因； +- 待办事项； +- 代码、命令、公式和数据； +- 尚未确认的信息。 + +合并重复内容，但保留不同来源之间的重要差异。 + +发现矛盾时不要擅自选择结论，应明确标记冲突或“待确认”。 + +不要把聊天时间顺序直接当作文档结构。 + +## 组织文档 + +根据内容选择必要章节，可以采用： + +```text +文档概述 +背景与目标 +核心概念 +方案或处理流程 +实现与操作说明 +关键参数 +问题与解决方法 +结论 +待确认事项 +后续计划 +``` diff --git a/.agents/skills/init-project-knowledge/SKILL.md b/.agents/skills/init-project-knowledge/SKILL.md new file mode 100644 index 0000000..f32b5f9 --- /dev/null +++ b/.agents/skills/init-project-knowledge/SKILL.md @@ -0,0 +1,49 @@ +--- +name: init-project-knowledge +description: "首次分析现有项目，创建或完善 AGENTS.md 和结构化项目知识库，并根据真实代码和资料进行初步填充。仅在用户显式调用 $init-project-knowledge 建立项目知识库时使用，不用于日常更新。" +--- + +# 初始化项目知识库 + +分析当前项目，建立一套轻量、结构化、可版本管理并适合 Codex 长期使用的项目知识库。 + +## 定位项目 + +1. 如果用户指定了项目路径，优先使用该路径。 +2. 否则从当前目录识别 Git 仓库根目录。 +3. 如果当前目录不是 Git 仓库，在工作区内浅层查找： + - 只有一个仓库时，使用该仓库； + - 存在多个仓库时，让用户选择； + - 没有仓库时，将当前项目目录作为目标。 +4. 记录项目绝对路径，后续分析和修改只针对该项目。 +5. 读取项目现有的 `AGENTS.md`、README 和主要文档。 + +不要根据文件夹名称猜测项目位置、技术栈或用途。 + +## 检查现有知识库 + +检查项目是否已经存在： + +- `AGENTS.md`； +- `docs/INDEX.md` 或其他文档索引； +- 项目概览、架构、接口、决策、问题和进度文档； +- 其他具有相同用途的知识文档。 + +如果已经存在完整知识库，不重复初始化，并建议使用 `$update-project-knowledge`。 + +如果知识库只完成了一部分，保留已有内容，只创建缺失文件并补充必要信息。 + +## 确定知识库位置 + +按照以下顺序选择知识库目录： + +1. 用户明确指定的目录； +2. 现有 `AGENTS.md` 声明的知识库目录； +3. 已经存在并承担项目文档用途的 `docs/`； +4. 默认使用项目根目录下的 `docs/`。 + +如果现有 `docs/` 已经用于其他用途，并且直接加入知识库可能造成混乱，先向用户确认是否使用： + +```text +docs/project-knowledge/ +``` diff --git a/.agents/skills/init-project-knowledge/agents/openai.yaml b/.agents/skills/init-project-knowledge/agents/openai.yaml new file mode 100644 index 0000000..7a0c62d --- /dev/null +++ b/.agents/skills/init-project-knowledge/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "初始化项目知识库" + short_description: "分析现有项目并创建可长期维护的结构化知识库与导航规则" + default_prompt: "使用 $init-project-knowledge 分析当前项目，并根据真实代码和资料建立项目知识库。" + +policy: + allow_implicit_invocation: false \ No newline at end of file diff --git a/.agents/skills/optimize-target-code/SKILL.md b/.agents/skills/optimize-target-code/SKILL.md new file mode 100644 index 0000000..e5acc64 --- /dev/null +++ b/.agents/skills/optimize-target-code/SKILL.md @@ -0,0 +1,75 @@ +--- +name: optimize-target-code +description: "分析并优化用户指定的函数、类、文件或小范围功能，改善实现效率、复杂度、数值稳定性、健壮性或可读性，并进行必要验证。仅在用户显式调用 $optimize-target-code 时使用。" +--- + +# 优化指定代码 + +对用户指定的小范围代码进行针对性优化，避免扩大修改范围。 + +## 执行流程 + +1. 读取适用的 `AGENTS.md`，确认目标文件、函数或功能。 +2. 读取目标代码、直接调用方、相关数据结构和测试，不扫描整个项目。 +3. 明确当前接口、输入输出、副作用、边界条件和预期行为。 +4. 检查： + - 不必要的循环、遍历、排序和重复计算； + - 不合适的数据结构和算法复杂度； + - 多余的对象创建、内存分配和数据复制； + - 浮点精度、除零、溢出、NaN 和边界输入； + - 过深嵌套、复杂条件和难以理解的代码结构； + - 热路径中的日志、IO、阻塞和共享状态。 +5. 选择收益明确、风险最低、修改最小的方案。 +6. 如果用户只要求“分析”或“检查”，给出建议但不修改代码。 +7. 如果用户要求“优化”或“改进”，直接实施行为保持型优化。 +8. 修改后运行最相关的测试或构建，并检查 diff。 + +## 修改原则 + +默认保持以下内容不变： + +- 公共接口和函数签名； +- 输入输出含义； +- 返回值和异常行为； +- 状态修改和副作用； +- 结果顺序和确定性； +- 线程和异步语义； +- 单位、坐标系、阈值和数值容差； +- 配置和序列化兼容性。 + +如果优化需要更换算法，并且可能改变结果、精度或适用范围，先说明新旧方案和风险，获得用户确认后再修改。 + +不要： + +- 顺便重构其他模块； +- 格式化整个文件或项目； +- 修改无关代码； +- 为了减少代码行数而过度抽象； +- 在没有测量时声称性能已经提升； +- 为通过测试而降低断言标准； +- 覆盖或回退用户原有改动。 + +## 性能验证 + +只有用户关注性能，或者修改明显针对性能时才进行基准测量。 + +优化前后使用相同输入、环境和构建模式，并重复运行。无法可靠测量时，只说明理论复杂度和预期收益，不声称实际性能提升。 + +## 特殊情况 + +对于数学、机器人、控制和实时代码，重点检查浮点误差、单位、坐标系、采样周期、角度归一化、饱和处理和实时周期，不擅自修改公式或参数。 + +硬件控制、部署和实机测试需要用户明确授权。 + +## 完成报告 + +简要报告： + +- 优化了哪个文件或函数； +- 发现了什么问题； +- 做了什么修改； +- 复杂度或预期收益； +- 执行了哪些测试或构建； +- 哪些内容尚未验证。 + +如果没有值得实施的安全优化，明确说明，不要强行修改代码。 \ No newline at end of file diff --git a/.agents/skills/optimize-target-code/agents/openai.yaml b/.agents/skills/optimize-target-code/agents/openai.yaml new file mode 100644 index 0000000..1340a5c --- /dev/null +++ b/.agents/skills/optimize-target-code/agents/openai.yaml @@ -0,0 +1,8 @@ + +interface: + display_name: "优化指定代码" + short_description: "分析并优化指定函数或文件，并用测试和基准验证改进效果" + default_prompt: "使用 $optimize-target-code 分析指定函数或文件，建立基线并实施可验证的最小优化。" + +policy: + allow_implicit_invocation: false \ No newline at end of file diff --git a/.agents/skills/readme/SKILL.md b/.agents/skills/readme/SKILL.md new file mode 100644 index 0000000..ee33e5f --- /dev/null +++ b/.agents/skills/readme/SKILL.md @@ -0,0 +1,182 @@ +--- +name: readme +description: "根据项目中的真实代码、配置和文档，同时创建、审查或更新英文 README.md 与中文 README_zh.md，确保两份项目说明内容一致、环境要求准确、使用命令可执行。仅在用户显式调用 $readme 时使用。" +--- + +# 维护中英文项目 README + +根据项目真实内容，同时创建或更新准确、简洁、可执行的英文和中文 README。 + +## 定位项目 + +1. 如果用户指定了项目路径，优先使用该路径。 +2. 否则使用当前 Git 仓库根目录。 +3. 如果当前目录不是 Git 仓库： + - 工作区内只有一个仓库时，使用该仓库； + - 存在多个仓库时，让用户选择； + - 没有 Git 仓库时，将当前目录作为项目根目录。 +4. 读取当前项目适用的 `AGENTS.md`。 +5. 默认维护项目根目录中的中英文 README。 + +不要根据文件夹名称猜测项目类型、用途或技术栈。 + +## 目标文件 + +默认维护： + +- `README.md`：英文版本； +- `README_zh.md`：简体中文版本。 + +如果项目已经使用 `README_CN.md`、`README_zh-CN.md` 等中文文件名，沿用已有命名，不重复创建中文 README。 + +如果两份 README 都存在，同时检查和更新。 + +如果只存在其中一份，根据已确认的项目内容创建缺少的版本。 + +如果 `README.md` 当前主要使用中文，且不存在独立中文版本： + +1. 先将仍然准确的中文内容保留到 `README_zh.md`； +2. 再将 `README.md` 整理为英文版本； +3. 确保原有有效信息没有丢失。 + +如果两份都不存在，同时创建英文和中文版本。 + +## 调研项目 + +优先检查： + +- 已有 README 和主要设计文档； +- 项目清单、依赖文件和包管理配置； +- 源码入口和核心模块； +- 构建、运行、测试和部署脚本； +- 配置示例和环境变量说明； +- CI 配置、许可证和贡献规范； +- `docs/` 中的索引或概览文档。 + +使用 `rg --files` 或等效方式进行针对性检查。 + +默认排除： + +- `.git`； +- `bin`、`obj`、`build`、`dist`； +- 日志、缓存和编译产物； +- 第三方依赖目录； +- 与 README 无关的大型数据和生成文件。 + +避免为了维护 README 扫描整个大型仓库。 + +## 同步规则 + +英文和中文 README 必须表达相同的项目事实，包括： + +- 项目目标和适用范围； +- 当前已经实现的功能； +- 环境和依赖要求； +- 安装、构建、运行和测试命令； +- 配置方法； +- 项目结构； +- 已知限制； +- 许可证和贡献方式。 + +两份 README 不要求逐字翻译，但章节含义、命令、路径、版本和项目状态必须一致。 + +代码、命令、配置键、类名、函数名和文件路径保持原文，不进行翻译。 + +如果只修改其中一份中的事实性内容，必须同步检查另一份。 + +不要让中文版本成为英文版本的简略摘要，也不要让其中一份长期落后于另一份。 + +## 语言切换 + +在英文 README 顶部添加中文版本链接，例如： + +`English | [简体中文](README_zh.md)` + +在中文 README 顶部添加英文版本链接，例如： + +`[English](README.md) | 简体中文` + +如果中文 README 使用其他文件名，应使用实际相对路径。 + +已有语言切换格式时，优先沿用现有格式。 + +## 确定修改范围 + +优先更新现有 README，保留仍然准确的内容和既有写作风格。 + +除非用户明确要求，默认只允许修改： + +- 英文 README； +- 中文 README。 + +不修改业务代码、配置、脚本或其他文档。 + +不创建中英文以外的语言版本。 + +复杂架构、接口和设计决策应链接到专门文档，不要全部复制进 README。 + +## 组织内容 + +根据项目实际情况选择必要章节，不强制套用完整模板。可以包括： + +1. 项目名称和一句话说明； +2. 当前能力和适用范围； +3. 快速开始； +4. 环境与依赖； +5. 构建、运行和测试； +6. 项目结构或架构概览； +7. 配置与部署； +8. 已知限制和故障排查； +9. 贡献方式和许可证。 + +把最常用、最可靠的使用路径放在前面。 + +两份 README 的主要章节和排列顺序应尽量保持一致。 + +只在确实有助于理解时使用表格、目录树或 Mermaid 图。 + +不要把 README 写成完整源码清单、开发日志或冗长设计文档。 + +## 保证准确 + +所有说明必须来自代码、配置、脚本、测试或现有文档。 + +命令必须能够在项目中找到依据，不得编造安装、构建、启动、测试、部署或硬件操作。 + +明确区分： + +- 已验证可用； +- 根据配置推断； +- 尚未验证。 + +不要把编译成功描述成运行成功、部署成功或实机验证成功。 + +不要编造版本、兼容平台、性能指标、维护状态或许可证。 + +不要写入密码、令牌、私有地址、个人绝对路径或其他敏感信息。 + +信息不足时优先省略非必要内容；必要信息缺失时标记为“待确认”。 + +已有中英文内容存在冲突时，以当前代码、配置和测试结果为准，并在结果中说明修正。 + +## 验证结果 + +完成后： + +- 检查两份 README 引用的文件和相对路径真实存在； +- 检查语言切换链接有效； +- 检查两份 README 的项目事实、命令和状态保持一致； +- 检查示例命令与项目文件保持一致； +- 安全且成本较低时，验证最关键的构建或测试命令； +- 未执行的命令必须明确说明； +- 检查最终 diff，避免无关重写、重复章节和格式噪声； +- 确认没有修改中英文 README 之外的文件。 + +最后报告： + +1. 创建或修改了哪些 README； +2. 主要新增或修正了什么内容； +3. 两份 README 同步了哪些信息； +4. 执行了哪些验证； +5. 哪些信息仍然待确认； +6. 确认没有修改其他文件。 \ No newline at end of file diff --git a/.agents/skills/readme/agents/openai.yaml b/.agents/skills/readme/agents/openai.yaml new file mode 100644 index 0000000..a0d0a63 --- /dev/null +++ b/.agents/skills/readme/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "维护中英文 README" + short_description: "根据项目真实内容同步创建或更新中英文 README" + default_prompt: "使用 $readme 根据当前项目的真实代码和配置，同步创建或更新英文 README.md 与中文 README_zh.md。" + +policy: + allow_implicit_invocation: false diff --git a/.agents/skills/reduce-code-redundancy/SKILL.md b/.agents/skills/reduce-code-redundancy/SKILL.md new file mode 100644 index 0000000..b18ffe8 --- /dev/null +++ b/.agents/skills/reduce-code-redundancy/SKILL.md @@ -0,0 +1,65 @@ +--- +name: reduce-code-redundancy +description: "审计代码库中的重复实现、未使用代码、冗余文件和可复用工具，并在不改变外部行为和业务逻辑的前提下安全清理已充分确认的冗余内容。仅在用户显式调用 $reduce-code-redundancy 时使用。" +--- + +# 清理代码库冗余 + +检查代码库中的重复实现、未使用代码、冗余文件和分散的通用功能，并安全清理能够充分确认的冗余内容。 + +## 工作模式 + +支持以下模式： + +- `mode=audit`：只分析并报告，不修改文件。 +- `mode=apply`：分析后清理已经充分确认的冗余。 +- 未指定模式：先执行审计，展示候选项并等待用户确认是否清理。 + +不要在证据不足时直接删除或合并代码。 + +## 定位代码库 + +1. 如果用户指定了项目路径，优先使用该路径。 +2. 否则识别当前 Git 仓库根目录。 +3. 如果当前目录不是 Git 仓库，在工作区内浅层查找： + - 只有一个仓库时使用该仓库； + - 存在多个仓库时让用户选择； + - 没有仓库时将当前项目目录作为目标。 +4. 读取项目适用的 `AGENTS.md`、README、构建配置和主要设计文档。 +5. 记录执行前已有的未提交改动，不覆盖或回退用户原有修改。 + +## 确定分析范围 + +优先使用用户指定的目录、模块或文件。 + +用户没有指定时，检查整个目标代码库，但使用针对性搜索，不无差别读取所有文件。 + +项目规模较大时： + +- 先统计主要源码目录和文件数量； +- 按模块分批检查； +- 优先检查近期修改、核心模块和公共工具目录； +- 不一次性加载整个大型代码库。 + +默认排除： + +- `.git`； +- `bin`、`obj`、`build`、`dist`； +- 日志、缓存和编译产物； +- 第三方依赖； +- 自动生成代码； +- 大型数据和模型文件； +- 用户没有要求处理的参考项目。 + +## 建立验证基线 + +修改前确认项目当前状态： + +```text +Git 状态 +当前分支 +构建方式 +测试方式 +已有静态检查工具 +当前构建和测试结果 +``` diff --git a/.agents/skills/reduce-code-redundancy/agents/openai.yaml b/.agents/skills/reduce-code-redundancy/agents/openai.yaml new file mode 100644 index 0000000..ef5bc9b --- /dev/null +++ b/.agents/skills/reduce-code-redundancy/agents/openai.yaml @@ -0,0 +1,8 @@ + +interface: + display_name: "清理代码库冗余" + short_description: "审计重复实现和无效代码，并安全清理已充分确认的冗余内容" + default_prompt: "使用 $reduce-code-redundancy 审计当前代码库，并在充分验证后清理能够确认的冗余内容。" + +policy: + allow_implicit_invocation: false \ No newline at end of file diff --git a/.agents/skills/trace-code-flow/SKILL.md b/.agents/skills/trace-code-flow/SKILL.md new file mode 100644 index 0000000..7940675 --- /dev/null +++ b/.agents/skills/trace-code-flow/SKILL.md @@ -0,0 +1,97 @@ +--- +name: trace-code-flow +description: "快速追踪用户指定功能从入口到输出的调用链、数据流、状态变化、单位和坐标系。只进行代码分析，不修改文件，仅在用户显式调用 $trace-code-flow 时使用。" +--- + +# 追踪代码执行流程 + +快速分析指定功能在代码中的完整执行路径，只读检查代码，不修改任何文件。 + +## 分析范围 + +1. 读取当前目录适用的 `AGENTS.md`。 +2. 以用户指定的函数、类、接口、事件或功能为起点。 +3. 用户未指定目标时，先询问，不默认扫描整个项目。 +4. 只检查完成追踪所必需的文件。 +5. 跳过第三方依赖、编译产物、缓存、日志和自动生成文件。 + +## 追踪内容 + +重点追踪： + +- 功能入口和触发条件； +- 上层调用者； +- 实际执行的函数和实现类； +- 参数和数据来源； +- 中间的数据转换； +- 条件分支和提前返回； +- 对象字段、全局状态和缓存的变化； +- 文件、数据库、网络、串口等外部交互； +- 最终返回值、输出消息或执行结果； +- 数值单位、坐标系、方向和角度约定。 + +## 分析原则 + +- 优先依据当前代码，不根据函数名猜测行为。 +- 区分接口声明、具体实现和实际调用位置。 +- 遇到重载、继承、事件、委托、回调或依赖注入时，确认可能执行的实现。 +- 无法静态确认的动态路径标记为“运行时决定”。 +- 每项重要结论尽量标注文件路径、类名和方法名。 +- 不展开与目标无关的辅助函数。 +- 不运行耗时较长的完整构建或测试，除非用户明确要求。 + +## 单位和坐标系 + +发现数值传递时，检查： + +- 长度是 `m`、`cm` 还是 `mm`； +- 速度是 `m/s`、`km/h` 还是其他单位； +- 角度是 `rad` 还是 `deg`； +- 时间是 `s`、`ms` 还是时间戳； +- 坐标属于世界、地图、车辆、传感器或局部坐标系； +- 是否存在缩放、归一化、符号取反或坐标变换。 + +代码不能确认时标记为“待确认”，不得自行推断。 + +## 输出格式 + +按照以下结构输出： + +```markdown +## 目标 + +功能、入口以及分析范围。 + +## 调用链 + +入口方法 +→ 中间方法 +→ 核心实现 +→ 输出方法 + +每一步标注对应文件和符号。 + +## 数据流 + +| 阶段 | 输入 | 处理 | 输出 | 单位/坐标系 | +|---|---|---|---|---| + +## 状态变化 + +| 位置 | 状态 | 变化 | 影响 | +|---|---|---|---| + +没有状态变化时明确说明。 + +## 分支与异常路径 + +说明关键条件分支、提前返回、异常处理和失败结果。 + +## 最终输出 + +说明最终返回值、发送消息、文件写入或硬件指令。 + +## 待确认 + +列出无法通过静态代码确定的信息。 +``` diff --git a/.agents/skills/trace-code-flow/agents/openai.yaml b/.agents/skills/trace-code-flow/agents/openai.yaml new file mode 100644 index 0000000..b6a7f63 --- /dev/null +++ b/.agents/skills/trace-code-flow/agents/openai.yaml @@ -0,0 +1,8 @@ + +interface: + display_name: "追踪代码流程" + short_description: "快速分析指定功能的调用链、数据流、状态和单位" + default_prompt: "使用 $trace-code-flow 追踪我指定功能从入口到最终输出的完整代码流程。" + +policy: + allow_implicit_invocation: false \ No newline at end of file diff --git a/.agents/skills/update-project-knowledge/SKILL.md b/.agents/skills/update-project-knowledge/SKILL.md new file mode 100644 index 0000000..4f2f7b6 --- /dev/null +++ b/.agents/skills/update-project-knowledge/SKILL.md @@ -0,0 +1,126 @@ +--- +name: update-project-knowledge +description: "检查已完成的项目工作，并仅在产生已确认、长期有效的信息时更新现有项目知识库。仅在用户显式调用 $update-project-knowledge 进行任务结束或每日收尾检查时使用。" +--- + +# 更新项目知识库 + +检查本次任务或当天工作，并按需同步到项目已有的结构化知识文档。 + +## 定位项目 + +1. 如果用户指定了项目路径，优先使用该路径。 +2. 否则从当前目录识别 Git 仓库根目录。 +3. 如果当前目录不是 Git 仓库，在工作区内浅层查找： + - 只有一个仓库时，使用该仓库； + - 存在多个仓库时，让用户选择； + - 没有仓库时，将当前项目目录作为目标。 +4. 记录目标项目的绝对路径，后续检查只针对该项目。 +5. 读取该项目适用的 `AGENTS.md`。 + +不要根据文件夹名称猜测项目位置。 + +## 定位知识库 + +按照以下顺序确定知识库位置： + +1. 优先使用用户明确指定的目录。 +2. 检查 `AGENTS.md` 是否声明了知识库路径。 +3. 检查项目中的 `docs/INDEX.md`、`docs/index.md` 或其他文档索引。 +4. 如果存在多个可能的知识库，先让用户选择。 +5. 如果不存在知识库或文档结构无法确认，停止执行并说明需要先建立知识库。 + +本 Skill 只更新已有知识库，不擅自创建新的知识库结构。 + +## 检查当前状态 + +执行前记录项目和知识文档已有的未提交变更，不覆盖或回退用户原有修改。 + +以只读方式检查： + +- 当前对话中已经完成的工作； +- 当前项目的 `git status --short`； +- 与本次任务相关的 `git diff`； +- 本次任务修改过的文件； +- 已执行的编译、测试或验证结果； +- 必要时检查与本次任务相关的最近提交。 + +如果项目不是 Git 仓库，则根据当前对话、文件修改和验证结果判断。 + +不要默认扫描整个项目或整个知识库。 + +## 判断是否需要更新 + +只记录已经确认、以后仍然有用的信息，例如： + +- 项目目标、业务场景或主要工作流程变化； +- 模块职责、依赖关系、调用关系或数据流变化； +- 接口、协议、数据结构、单位、坐标系或输入输出变化； +- 已经确认的技术决策及其限制； +- 已定位并验证的问题、原因和解决方案； +- 实际完成进度、当前阻塞项和下一步变化。 + +如果没有产生长期有效的信息，不修改任何文档，并报告“本次无需更新知识库”。 + +## 选择文档 + +优先读取知识库索引，根据索引确定需要修改的文档。 + +如果项目采用以下常见文档，可以参考对应关系： + +- `overview.md`：项目背景、目标、场景和整体流程； +- `architecture.md`：目录结构、模块职责、依赖、调用关系和数据流； +- `interfaces.md`：接口、协议、数据结构、单位和输入输出； +- `decisions.md`：技术决策、原因、替代方案和限制； +- `problems.md`：问题现象、根因、解决方法和验证结果； +- `progress.md`：已完成、进行中、阻塞项和下一步； +- `INDEX.md`：知识库导航和文档职责。 + +这些文件名不是强制要求。项目已有其他结构时，遵循现有索引和文档约定。 + +只读取并修改与本次变化直接相关的文档，不要默认读取整个知识库。 + +## 记录原则 + +- 只记录能够从代码、配置、测试结果、Git 变更或用户确认中得到支持的信息。 +- 重要结论尽量标注相关文件路径、模块、类名或方法名。 +- 无法确认的信息标记为“待确认”，不得自行补全。 +- 区分“已经实施”和“计划采用”。 +- 区分“已解决”和“待解决”。 +- 只修改相关章节，不重写整个文档。 +- 避免在多个文档中重复保存相同内容。 +- 进度文档只保存当前状态，不积累成长篇开发日志。 +- 保留文档原有语言、结构和写作风格。 + +## 不应记录 + +不要记录： + +- 普通聊天和临时想法； +- 尚未验证的猜测； +- 没有长期参考价值的失败尝试； +- 冗长终端输出、编译日志和完整代码； +- 可以直接从代码中轻易查到的低价值细节； +- 密钥、密码、令牌、私有地址和个人路径。 + +## 安全限制 + +- 只允许修改已经确认的知识库目录。 +- 不修改业务代码、配置文件、测试和构建脚本。 +- 不修改任何 `AGENTS.md`。 +- 不删除、移动或重命名现有文件。 +- 不覆盖或回退执行前已经存在的用户改动。 +- 不扫描 `.git`、日志、缓存、编译产物和第三方依赖。 +- 不读取或修改目标项目之外的其他项目，除非用户明确要求。 +- 发现知识文档与当前代码存在明显冲突时，说明冲突并保留依据，不直接覆盖原结论。 + +## 完成检查 + +完成后检查本次产生的文件差异，并报告： + +1. 本次是否需要更新知识库； +2. 修改了哪些知识文档； +3. 新增或修正了哪些长期信息； +4. 哪些信息仍然待确认； +5. 本次 Skill 是否只修改了知识库目录； +6. 工作区中是否存在执行前就已经存在的其他改动。 \ No newline at end of file diff --git a/.agents/skills/update-project-knowledge/agents/openai.yaml b/.agents/skills/update-project-knowledge/agents/openai.yaml new file mode 100644 index 0000000..c3dbef9 --- /dev/null +++ b/.agents/skills/update-project-knowledge/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "更新项目知识库" + short_description: "检查本次工作并按需更新项目中长期有效的结构化知识文档" + default_prompt: "使用 $update-project-knowledge 检查本次项目工作，并仅在必要时更新已有知识库。" + +policy: + allow_implicit_invocation: false \ No newline at end of file diff --git a/.claude/CLAUDE/CLAUDE_styletalk.md b/.claude/CLAUDE/CLAUDE_styletalk.md new file mode 100644 index 0000000..956a9b7 --- /dev/null +++ b/.claude/CLAUDE/CLAUDE_styletalk.md @@ -0,0 +1,93 @@ +# CLAUDE.md + +你是我的高效编程与工程学习助手。默认使用中文回答。目标是简洁、直接、段落清楚、有效信息密度高。 + +## Response Style + +先给结论，再给必要解释。 + +默认使用短段落。只有在步骤、对比、排查路径确实需要时才使用列表。 + +不要寒暄，不要铺垫，不要表情，不要夸奖式废话。 + +不要为了显得完整而扩展无关背景。只回答当前问题，并给出最实用的下一步。 + +如果可以直接判断，就直接判断。不要反复使用“可能、也许、大概”。 + +如果不确定，直接说“不确定”，并说明需要查看哪个文件、日志、命令输出、配置项或代码位置。 + +## Default Answer Pattern + +普通问题默认按这个顺序回答： + +结论。 + +原因。 + +下一步操作。 + +如果问题很简单，只回答结论和操作，不要强行展开。 + +## Engineering Behavior + +解释工程问题时，优先讲清楚：它是什么、为什么需要、现在该怎么做。 + +不要写教科书式背景。不要从概念历史讲起。 + +涉及代码、项目结构、编译、运行、调试时，优先给可执行操作，不要只讲原理。 + +如果我贴日志，先找最早出现的关键 error，不要逐条解释所有报错。 + +如果我贴截图，直接说明截图里的关键信息、当前状态、下一步点击或配置什么。 + +如果我问“这样对吗”，直接回答：对 / 不对 / 部分对。然后指出关键误区。 + +如果我问“这是什么问题”，优先回答： + +根因。 + +现在该做什么。 + +不要做什么。 + +## Claude Code Workflow + +修改代码前，先阅读相关文件，确认现有实现方式，不要凭空假设。 + +优先做最小改动。不要主动大范围重构，除非我明确要求。 + +改代码时保持当前项目风格，不要引入不必要的新依赖、新框架或复杂抽象。 + +给命令时，只给当前步骤需要执行的命令。不要一次性堆很多备用命令。 + +修改后如果项目有明确的 build、test、lint 命令，应说明需要运行哪个命令验证。 + +如果命令可能删除、覆盖、重置、清理缓存或修改全局配置，必须先说明影响。 + +不要在没有证据时说“已经修好”。需要用编译结果、测试结果、日志或运行输出来证明。 + +## Writing Tasks + +如果我让你写日报、汇报、说明、消息、邮件，输出要像真实职场表达。 + +文字要短、自然、具体。不要写成作文，不要过度正式，不要堆套话。 + +如果是给领导或同事看的内容，默认语气稳妥、简洁、低调。 + +## Learning Mode + +用户是工程背景，不需要过度科普。 + +解释新技术时，用“工程用途 + 当前项目里怎么用 + 最小上手路径”的方式说明。 + +避免抽象概念堆叠。能结合代码、目录、命令、接口、日志，就不要只讲概念。 + +## Boundaries + +不要主动跑题。 + +不要在回答末尾反复总结。 + +不要每次都问“是否需要我继续”。只有在确实缺少关键信息时才问问题。 + +不要输出过长答案。默认控制在能直接读完并执行的长度。 \ No newline at end of file diff --git a/.codex/AGENT/AGENTS_claudestyletalk.md b/.codex/AGENT/AGENTS_claudestyletalk.md new file mode 100644 index 0000000..2658d04 --- /dev/null +++ b/.codex/AGENT/AGENTS_claudestyletalk.md @@ -0,0 +1,89 @@ +# AGENTS.md + +你是我的高效编程与工程学习助手。默认使用中文回答。目标是像 Claude 一样简洁、直接、段落清楚、信息密度高。 + +## Core Style + +先给结论，再给必要解释。 + +默认使用短段落。除非步骤、对比、排查路径确实需要，否则不要使用长列表。 + +不要寒暄，不要铺垫，不要夸奖式废话，不要使用表情。 + +不要为了显得完整而扩展无关背景。只回答当前问题，并给出最实用的下一步。 + +如果可以直接判断，就直接判断。不要反复使用“可能、也许、大概”来稀释结论。 + +如果不确定，直接说“不确定”，并说明需要查看哪个文件、日志、命令输出、配置项或代码位置。 + +## Answer Format + +普通问题默认使用这个顺序： + +结论。 + +原因。 + +下一步操作。 + +如果问题很简单，只回答结论和操作，不要强行展开。 + +## Engineering Rules + +解释工程问题时，优先讲清楚“它是什么、为什么需要、我现在该怎么做”。 + +不要写教科书式背景。不要从概念历史讲起。 + +涉及代码、项目结构、编译、运行、调试时，优先给可执行操作，不要只讲原理。 + +如果用户贴日志，先找最早出现的关键 error。不要逐条解释所有报错。 + +如果用户贴截图，直接说明截图里的关键信息、当前状态、下一步点击或配置什么。 + +如果用户问“这样对吗”，直接回答：对 / 不对 / 部分对。然后指出关键误区。 + +如果用户问“这是什么问题”，优先回答： + +根因。 + +现在该做什么。 + +不要做什么。 + +## Code and Debugging + +不要在没看项目文件、报错信息或上下文时编造结论。 + +修改代码前，先判断影响范围。不要做大而全的重构。 + +优先给最小修改方案。除非用户明确要求优化架构，否则不要主动扩大改动。 + +给命令时，只给当前步骤需要执行的命令。不要一次性堆很多备用命令。 + +如果有风险命令，例如删除、覆盖、重置、清理缓存、修改全局配置，必须先说明影响。 + +## Writing Tasks + +如果用户让你写日报、汇报、说明、消息、邮件，输出要像真实职场表达。 + +文字要短、自然、具体。不要写成作文，不要过度正式，不要堆套话。 + +如果是给领导或同事看的内容，默认语气稳妥、简洁、低调。 + +## Learning Mode + +用户是工程背景，不需要过度科普。 + +解释新技术时，用“工程用途 + 当前项目里怎么用 + 最小上手路径”的方式说明。 + +避免抽象概念堆叠。能结合代码、目录、命令、接口、日志，就不要只讲概念。 + +## Boundaries + +不要主动跑题。 + +不要在回答末尾反复总结。 + +不要每次都问“是否需要我继续”。只有在确实缺少关键信息时才问问题。 + +不要输出过长答案。默认控制在能直接读完并执行的长度。 \ No newline at end of file diff --git a/.cursor/rules/karpathy-guidelines.mdc b/.cursor/rules/karpathy-guidelines.mdc new file mode 100644 index 0000000..edd317f --- /dev/null +++ b/.cursor/rules/karpathy-guidelines.mdc @@ -0,0 +1,70 @@ +--- +description: Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria. +alwaysApply: true +--- + +# Karpathy behavioral guidelines + +Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed. + +**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment. + +## 1. Think Before Coding + +**Don't assume. Don't hide confusion. Surface tradeoffs.** + +Before implementing: +- State your assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them - don't pick silently. +- If a simpler approach exists, say so. Push back when warranted. +- If something is unclear, stop. Name what's confusing. Ask. + +## 2. Simplicity First + +**Minimum code that solves the problem. Nothing speculative.** + +- No features beyond what was asked. +- No abstractions for single-use code. +- No "flexibility" or "configurability" that wasn't requested. +- No error handling for impossible scenarios. +- If you write 200 lines and it could be 50, rewrite it. + +Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. + +## 3. Surgical Changes + +**Touch only what you must. Clean up only your own mess.** + +When editing existing code: +- Don't "improve" adjacent code, comments, or formatting. +- Don't refactor things that aren't broken. +- Match existing style, even if you'd do it differently. +- If you notice unrelated dead code, mention it - don't delete it. + +When your changes create orphans: +- Remove imports/variables/functions that YOUR changes made unused. +- Don't remove pre-existing dead code unless asked. + +The test: Every changed line should trace directly to the user's request. + +## 4. Goal-Driven Execution + +**Define success criteria. Loop until verified.** + +Transform tasks into verifiable goals: +- "Add validation" → "Write tests for invalid inputs, then make them pass" +- "Fix the bug" → "Write a test that reproduces it, then make it pass" +- "Refactor X" → "Ensure tests pass before and after" + +For multi-step tasks, state a brief plan: +``` +1. [Step] → verify: [check] +2. [Step] → verify: [check] +3. [Step] → verify: [check] +``` + +Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. + +--- + +**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes. diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..7d91e3c --- /dev/null +++ b/.editorconfig @@ -0,0 +1,32 @@ +root = true + +# 全局默认 +[*] +charset = utf-8 +end_of_line = lf +indent_style = space +indent_size = 4 +insert_final_newline = true +trim_trailing_whitespace = true + +# Python +[*.py] +indent_size = 4 +max_line_length = 88 + +# Web & 配置文件（2格缩进） +[*.{js,ts,jsx,tsx,css,scss,html,json,yaml,yml,toml}] +indent_size = 2 + +# Markdown（保留行尾空格，两个空格是换行语法） +[*.md] +trim_trailing_whitespace = false +indent_size = 2 + +# Makefile 必须用 tab +[Makefile] +indent_style = tab + +# Shell +[*.{sh,bash,zsh}] +indent_size = 2 \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..81e23e8 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 DreamCasterZero + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..6c2f643 --- /dev/null +++ b/README.md @@ -0,0 +1,104 @@ +English | [简体中文](README_zh.md) + +# Zero-DevToolbox + +> A compact collection of reusable, low-coupling skills for AI-assisted development across projects. + +![License](https://img.shields.io/badge/License-MIT-green) + +Zero-DevToolbox currently provides nine opt-in workflow skills under `.agents/skills/`. Unlike skills written around one application's architecture or business rules, these skills contain project-agnostic workflows that inspect the target repository at runtime. Copy the collection, or only the skill directories you need, into a new project and use them without rewriting their core instructions. + +The skills address recurring development problems such as redundant code, difficult code-flow analysis, inconsistent documentation, repetitive Git delivery, and project context being lost between Codex sessions. The repository also includes a Cursor rule, shared ignore templates, and EditorConfig settings. + +## Why these skills are reusable + +- **Low coupling:** the workflows do not hard-code a specific application's modules, framework, data model, or business logic. They derive relevant details from the target project's code, configuration, tests, `AGENTS.md`, and documentation. +- **Portable by design:** each skill has a focused responsibility and lives in its own directory. Copy the complete `.agents/skills/` collection or select only the workflows a project needs. +- **Focused and concise:** skills operate on an explicit target, avoid unrelated changes, and include safety and verification rules for common development tasks. +- **Context continuity:** `$init-project-knowledge` creates a lightweight, structured, version-controlled project knowledge base, while `$update-project-knowledge` records only confirmed, durable changes. Together they reduce the loss of important project context across sessions. +- **Different from project-specific skills:** project-specific skills encode one repository's architecture or internal process. Zero-DevToolbox supplies general workflows that adapt to the repository where they are installed. + +## Included skills + +Invoke each skill explicitly with its `$skill-name`. All bundled `agents/openai.yaml` files disable implicit invocation. + +| Skill | Purpose | +|---|---| +| `$add-code-comments` | Add concise comments to a specified code scope without changing behavior; intended for languages that support `//` comments. | +| `$commit` | Inspect Git changes, prepare a repository-style commit message, then stage, commit, and push the selected changes. | +| `$generate-latex-document` | Turn notes or codebase analysis into a standalone `.tex` document using the bundled template; it does not compile a PDF locally. | +| `$init-project-knowledge` | Analyze a project and initialize or complete an `AGENTS.md`-guided, structured knowledge base. | +| `$optimize-target-code` | Analyze and optimize a specified function, class, file, or small feature while preserving behavior and validating the change. | +| `$readme` | Create, review, or synchronize English and Chinese READMEs from the project's actual code, configuration, scripts, and documentation. | +| `$reduce-code-redundancy` | Audit duplicate implementations, unused code, redundant files, and reusable utilities; cleanup requires verified evidence. | +| `$trace-code-flow` | Read-only tracing of a specified feature's call chain, data flow, state changes, units, and coordinate systems. | +| `$update-project-knowledge` | Update an existing knowledge base only when completed work produced confirmed, durable information. | + +## Quick start + +Clone the repository: + +```bash +git clone https://github.com/DreamCasterZero/Zero-DevToolbox.git +``` + +For a tool that discovers project-local skills from `.agents/skills/`, copy the full collection or selected skill directories into the target project's `.agents/skills/` directory. + +macOS/Linux: + +```bash +mkdir -p /path/to/your-project/.agents +cp -R Zero-DevToolbox/.agents/skills /path/to/your-project/.agents/ +``` + +PowerShell: + +```powershell +New-Item -ItemType Directory -Force C:\path\to\your-project\.agents +Copy-Item -Recurse Zero-DevToolbox\.agents\skills C:\path\to\your-project\.agents\ +``` + +Then invoke the required workflow explicitly: + +```text +$trace-code-flow trace the checkout request from its API endpoint to the database write. +$optimize-target-code optimize the parser in src/parser.ts and run its focused tests. +$readme check this project and update its English and Chinese READMEs. +``` + +Each `SKILL.md` defines the workflow's scope, safety rules, validation, and completion report. Workflows that need a target file or feature ask for that scope instead of scanning the entire project. + +## Supporting configuration + +### Cursor rule + +`.cursor/rules/karpathy-guidelines.mdc` is an always-applied Cursor rule that emphasizes surfaced assumptions, simple solutions, focused changes, and verifiable success criteria. Copy `.cursor/` into a project to use it there. + +### Ignore templates + +`ignore/` contains `.gitignore`, `.claudeignore`, and `.cursorignore` templates covering common secrets, dependencies, generated output, logs, databases, media, editor metadata, and caches. + +Review the patterns before copying a template: the defaults intentionally exclude items such as lock files and images, which some projects should commit. + +### EditorConfig + +`.editorconfig` sets UTF-8 and LF defaults, final newlines, trailing-whitespace behavior, and indentation for Python, web/config files, Markdown, Makefiles, and shell scripts. + +## Repository layout + +```text +.agents/skills/ Nine explicitly invoked workflow skills + generate-latex-document/ Includes a template and two workflow references +.cursor/rules/ Always-applied Cursor coding guideline +ignore/ Git, Claude Code, and Cursor ignore templates +.editorconfig Shared editor formatting +LICENSE MIT license +README.md English project overview +README_zh.md Chinese project overview +``` + +This repository contains configuration and Markdown/LaTeX resources rather than an executable application, so it has no package installation, build, or automated test command. + +## License + +Licensed under the [MIT License](LICENSE). Copyright (c) 2026 DreamCasterZero. diff --git a/README_zh.md b/README_zh.md new file mode 100644 index 0000000..0037b9a --- /dev/null +++ b/README_zh.md @@ -0,0 +1,104 @@ +[English](README.md) | 简体中文 + +# Zero-DevToolbox + +> 一套简洁、通用、低耦合，可跨项目复用的 AI 辅助开发 Skill。 + +![License](https://img.shields.io/badge/License-MIT-green) + +Zero-DevToolbox 目前在 `.agents/skills/` 下提供 9 个按需调用的工作流 Skill。与围绕某个具体项目架构或业务规则编写的 Skill 不同，这些 Skill 保存的是通用工作流，执行时再读取目标仓库的真实内容。将整套 Skill 或所需的单个 Skill 目录复制到新项目后，即可直接使用，无需重写核心指令。 + +这些 Skill 用于解决开发中的常见问题，包括代码冗余、调用流程难以追踪、文档不一致、Git 交付流程重复，以及 Codex 跨会话后项目上下文丢失。仓库还包含 Cursor 规则、通用 ignore 模板和 EditorConfig 配置。 + +## 为什么适合跨项目复用 + +- **低耦合：** 工作流不写死某个应用的模块、框架、数据模型或业务逻辑，而是从目标项目的代码、配置、测试、`AGENTS.md` 和文档中获取所需信息。 +- **可直接迁移：** 每个 Skill 职责单一并拥有独立目录。可以复制完整的 `.agents/skills/`，也可以只选择当前项目需要的工作流。 +- **简洁且聚焦：** Skill 围绕明确目标执行，避免无关修改，并为常见开发任务内置安全边界和验证要求。 +- **保持上下文连续：** `$init-project-knowledge` 会创建轻量、结构化、可版本管理的项目知识库，`$update-project-knowledge` 只记录经过确认且长期有效的变化，两者共同减少跨会话时重要项目上下文的丢失。 +- **区别于项目专用 Skill：** 项目专用 Skill 通常固化某个仓库的架构或内部流程；Zero-DevToolbox 提供的是能够适应安装目标仓库的通用工作流。 + +## 内置 Skill + +所有 Skill 都需要使用 `$skill-name` 显式调用。每个 Skill 附带的 `agents/openai.yaml` 均已禁用隐式调用。 + +| Skill | 用途 | +|---|---| +| `$add-code-comments` | 为指定代码范围补充简洁注释且不改变行为；适用于支持 `//` 注释的语言。 | +| `$commit` | 检查 Git 改动、生成符合仓库风格的提交信息，然后暂存、提交并推送选定改动。 | +| `$generate-latex-document` | 使用内置模板将笔记或代码库分析整理为独立的 `.tex` 文档；不会在本地编译 PDF。 | +| `$init-project-knowledge` | 分析项目并初始化或完善由 `AGENTS.md` 引导的结构化知识库。 | +| `$optimize-target-code` | 分析并优化指定函数、类、文件或小范围功能，同时保持行为并验证修改。 | +| `$readme` | 根据项目真实代码、配置、脚本和文档创建、检查或同步中英文 README。 | +| `$reduce-code-redundancy` | 审计重复实现、未使用代码、冗余文件和可复用工具；仅清理证据充分的内容。 | +| `$trace-code-flow` | 以只读方式追踪指定功能的调用链、数据流、状态变化、单位和坐标系。 | +| `$update-project-knowledge` | 仅在已完成工作产生经过确认且长期有效的信息时更新现有项目知识库。 | + +## 快速开始 + +克隆仓库： + +```bash +git clone https://github.com/DreamCasterZero/Zero-DevToolbox.git +``` + +如果 AI 编码工具从 `.agents/skills/` 发现项目级 Skill，请将完整集合或选定的 Skill 目录复制到目标项目的 `.agents/skills/` 目录。 + +macOS/Linux： + +```bash +mkdir -p /path/to/your-project/.agents +cp -R Zero-DevToolbox/.agents/skills /path/to/your-project/.agents/ +``` + +PowerShell： + +```powershell +New-Item -ItemType Directory -Force C:\path\to\your-project\.agents +Copy-Item -Recurse Zero-DevToolbox\.agents\skills C:\path\to\your-project\.agents\ +``` + +随后在 AI 编码会话中显式调用所需工作流： + +```text +$trace-code-flow 追踪结账请求从 API 端点到数据库写入的流程。 +$optimize-target-code 优化 src/parser.ts 中的解析器并运行相关测试。 +$readme 检查当前项目并更新中英文 README。 +``` + +每个 `SKILL.md` 都定义了工作流的范围、安全规则、验证方式和完成报告。需要目标文件或功能的工作流会要求用户明确范围，不会直接扫描整个项目。 + +## 配套配置 + +### Cursor 规则 + +`.cursor/rules/karpathy-guidelines.mdc` 是一条始终应用的 Cursor 规则，强调明确假设、采用简单方案、保持改动聚焦，以及定义可验证的成功标准。将 `.cursor/` 复制到项目中即可使用。 + +### Ignore 模板 + +`ignore/` 包含 `.gitignore`、`.claudeignore` 和 `.cursorignore` 模板，覆盖常见密钥、依赖、生成内容、日志、数据库、媒体文件、编辑器元数据和缓存。 + +复制前请检查具体规则：默认模板会忽略锁文件和图片等内容，而部分项目需要提交这些文件。 + +### EditorConfig + +`.editorconfig` 设置 UTF-8、LF、文件末尾换行、行尾空格处理方式，以及 Python、Web/配置文件、Markdown、Makefile 和 Shell 脚本的缩进。 + +## 仓库结构 + +```text +.agents/skills/ 9 个需要显式调用的工作流 Skill + generate-latex-document/ 包含一个模板和两份工作流参考 +.cursor/rules/ 始终应用的 Cursor 编码规则 +ignore/ Git、Claude Code 和 Cursor ignore 模板 +.editorconfig 通用编辑器格式配置 +LICENSE MIT 许可证 +README.md 英文项目说明 +README_zh.md 中文项目说明 +``` + +本仓库包含配置以及 Markdown/LaTeX 资源，不是可执行应用，因此没有依赖安装、构建或自动测试命令。 + +## 许可证 + +本项目采用 [MIT License](LICENSE)。Copyright (c) 2026 DreamCasterZero。 diff --git a/Zero-DevToolbox-Technical-Document.tex b/Zero-DevToolbox-Technical-Document.tex new file mode 100644 index 0000000..4719398 --- /dev/null +++ b/Zero-DevToolbox-Technical-Document.tex @@ -0,0 +1,596 @@ + +\documentclass[12pt,a4paper]{article} + +% ============================================================ +% 中文技术文档模板 +% 建议在 Overleaf 中使用 XeLaTeX 编译 +% ============================================================ + +\usepackage[UTF8]{ctex} +\usepackage[margin=2.5cm]{geometry} +\usepackage{titlesec} +\usepackage{fancyhdr} +\usepackage{listings} +\usepackage{xcolor} +\usepackage{graphicx} +\usepackage{amsmath} +\usepackage{amssymb} +\usepackage{booktabs} +\usepackage{longtable} +\usepackage{tabularx} +\usepackage{array} +\usepackage{enumitem} +\usepackage{tcolorbox} +\usepackage{setspace} +\usepackage{url} +\usepackage{hyperref} + +\tcbuselibrary{skins,breakable} + +% ============================================================ +% 页面设置 +% ============================================================ + +\geometry{ + a4paper, + left=2.5cm, + right=2.5cm, + top=2.5cm, + bottom=2.5cm +} + +\onehalfspacing +\setlength{\parindent}{2em} +\setlength{\parskip}{0.3em} +\setlength{\emergencystretch}{2em} + +\setlist[itemize]{ + itemsep=0.2em, + topsep=0.4em +} + +\setlist[enumerate]{ + itemsep=0.2em, + topsep=0.4em +} + +\setcounter{tocdepth}{2} +\setcounter{secnumdepth}{3} + +% ============================================================ +% 文档信息占位符 +% ============================================================ + +\newcommand{\doctitle}{Zero-DevToolbox 技术文档} +\newcommand{\docsubtitle}{通用、低耦合、跨项目复用的 AI 辅助开发 Skill 参考} +\newcommand{\projectname}{Zero-DevToolbox} +\newcommand{\docauthor}{项目组} +\newcommand{\docversion}{v1.0} +\newcommand{\docdescription}{本文档说明 Zero-DevToolbox 的项目定位、Skill 架构、主要工作流、安装方式、知识库机制、配套配置与已知限制。} + +% ============================================================ +% 颜色 +% ============================================================ + +\definecolor{primaryblue}{RGB}{35,85,145} +\definecolor{secondaryblue}{RGB}{65,105,170} +\definecolor{codebg}{RGB}{247,248,250} +\definecolor{codeframe}{RGB}{205,210,218} +\definecolor{codegreen}{RGB}{40,130,80} +\definecolor{codegray}{RGB}{110,115,125} +\definecolor{codepurple}{RGB}{145,70,165} +\definecolor{warningorange}{RGB}{210,125,30} +\definecolor{softgray}{RGB}{245,245,245} + +% ============================================================ +% 页眉页脚 +% ============================================================ + +\pagestyle{fancy} +\fancyhf{} +\fancyhead[L]{\small\doctitle} +\fancyhead[R]{\small\leftmark} +\fancyfoot[C]{\thepage} +\renewcommand{\headrulewidth}{0.4pt} +\renewcommand{\footrulewidth}{0pt} + +% ============================================================ +% 标题格式 +% ============================================================ + +\titleformat{\section} + {\Large\bfseries\color{primaryblue}} + {\thesection} + {1em} + {} + [\titlerule] + +\titleformat{\subsection} + {\large\bfseries\color{secondaryblue}} + {\thesubsection} + {1em} + {} + +\titleformat{\subsubsection} + {\normalsize\bfseries} + {\thesubsubsection} + {1em} + {} + +% ============================================================ +% 表格 +% ============================================================ + +\newcolumntype{Y}{>{\raggedright\arraybackslash}X} +\renewcommand{\arraystretch}{1.25} + +% ============================================================ +% 代码样式 +% ============================================================ + +\lstdefinestyle{codestyle}{ + backgroundcolor=\color{codebg}, + commentstyle=\color{codegreen}, + keywordstyle=\color{primaryblue}\bfseries, + numberstyle=\tiny\color{codegray}, + stringstyle=\color{codepurple}, + basicstyle=\ttfamily\footnotesize, + breakatwhitespace=false, + breaklines=true, + captionpos=b, + keepspaces=true, + numbers=left, + numbersep=8pt, + showspaces=false, + showstringspaces=false, + showtabs=false, + tabsize=4, + frame=single, + rulecolor=\color{codeframe}, + columns=fullflexible +} + +\lstdefinestyle{commandstyle}{ + backgroundcolor=\color{codebg}, + basicstyle=\ttfamily\footnotesize, + breaklines=true, + frame=single, + rulecolor=\color{codeframe}, + numbers=none, + columns=fullflexible +} + +\lstdefinelanguage{json}{ + basicstyle=\ttfamily\footnotesize, + string=[s]{}{}, + stringstyle=\color{codepurple}, + comment=[l]{//}, + commentstyle=\color{codegreen}, + keywords={true,false,null}, + keywordstyle=\color{primaryblue}\bfseries +} + +\lstset{style=codestyle} + +% ============================================================ +% 信息框 +% ============================================================ + +\newtcolorbox{infobox}[2][]{ + enhanced, + breakable, + colback=blue!4!white, + colframe=primaryblue, + fonttitle=\bfseries, + title={#2}, + #1 +} + +\newtcolorbox{warningbox}[2][]{ + enhanced, + breakable, + colback=orange!5!white, + colframe=warningorange, + fonttitle=\bfseries, + title={#2}, + #1 +} + +\newtcolorbox{filebox}[2][]{ + enhanced, + breakable, + colback=softgray, + colframe=gray!65!black, + fonttitle=\bfseries\ttfamily, + title={文件：#2}, + #1 +} + +\newtcolorbox{functionbox}[2][]{ + enhanced, + breakable, + colback=blue!2!white, + colframe=secondaryblue, + fonttitle=\bfseries\ttfamily, + title={函数：#2}, + #1 +} + +\newtcolorbox{qabox}[2][]{ + enhanced, + breakable, + colback=blue!4!white, + colframe=primaryblue, + fonttitle=\bfseries, + title={问题：#2}, + #1 +} + +\newtcolorbox{answerbox}[1][]{ + enhanced, + breakable, + colback=green!4!white, + colframe=green!55!black, + leftrule=4pt, + #1 +} + +% ============================================================ +% 行内代码 +% ============================================================ + +\newcommand{\code}[1]{\texttt{\detokenize{#1}}} + +% ============================================================ +% 超链接 +% ============================================================ + +\hypersetup{ + colorlinks=true, + linkcolor=primaryblue, + urlcolor=primaryblue, + citecolor=green!50!black, + bookmarks=true, + bookmarksnumbered=true, + pdftitle={\doctitle}, + pdfauthor={\docauthor} +} + +% ============================================================ +% 文档正文 +% ============================================================ + +\begin{document} + +% ============================================================ +% 封面 +% ============================================================ + +\begin{titlepage} + \centering + \vspace*{2.8cm} + + {\Huge\bfseries\color{primaryblue}\doctitle\par} + + \vspace{0.7cm} + + {\Large\docsubtitle\par} + + \vspace{2cm} + + \rule{\linewidth}{0.6mm} + + \vspace{1cm} + + \begin{tabular}{rl} + \textbf{项目或主题：} & \projectname \\[0.6em] + \textbf{作者：} & \docauthor \\[0.6em] + \textbf{日期：} & \today \\[0.6em] + \textbf{版本：} & \docversion + \end{tabular} + + \vspace{1cm} + + \rule{\linewidth}{0.6mm} + + \vfill + + \begin{minipage}{0.85\textwidth} + \centering + \small + \docdescription + \end{minipage} +\end{titlepage} + +% ============================================================ +% 目录 +% ============================================================ + +\tableofcontents +\newpage + +% ============================================================ +% 正文占位符 +% ============================================================ + + +\section{文档概述} + +本文档面向 Zero-DevToolbox 的使用者与维护者，基于当前工作树中的 README、Skill 定义、元数据、模板、Cursor 规则、ignore 模板、EditorConfig、许可证及 Git 信息整理。分析范围采用默认的 \code{scope=core}，重点描述对外可复用的工作流、配置结构和使用路径。 + +\begin{infobox}{范围说明} +Zero-DevToolbox 是配置与文档资源仓库，不包含传统应用程序入口、业务类、运行时服务或公共 API。因此本文不虚构类图、函数签名、数据库结构、性能指标或部署流程，而是将 Skill 目录视为主要功能模块。 +\end{infobox} + +\section{项目简介} + +Zero-DevToolbox 是一套简洁、通用、低耦合、可跨项目复用的 AI 辅助开发 Skill 集合。与绑定单一项目架构、框架或业务规则的 Skill 不同，本仓库提供可迁移的工作流定义；Skill 在执行时读取目标项目的代码、配置、测试、\code{AGENTS.md} 和文档，再确定具体操作。 + +当前仓库包含 9 个需要显式调用的工作流 Skill，主要解决以下开发问题： + +\begin{itemize} + \item 代码注释不足、局部实现复杂以及重复代码逐渐累积； + \item 功能调用链、数据流、状态变化、单位和坐标系难以快速理解； + \item README 与真实代码或配置长期不同步； + \item Git 提交、提交信息生成和推送过程重复； + \item Codex 跨会话后容易丢失项目背景、决策、问题和进度； + \item 零散笔记或代码库知识缺少结构化技术文档。 +\end{itemize} + +\subsection{设计目标} + +\begin{itemize} + \item \textbf{低耦合：}不写死目标项目的模块、框架、数据模型或业务逻辑。 + \item \textbf{可迁移：}可以复制整套 \code{.agents/skills/}，也可以只复制单个 Skill 目录。 + \item \textbf{职责单一：}每个 Skill 聚焦一个明确工作流，并通过显式调用启动。 + \item \textbf{安全可验证：}Skill 定义中包含范围控制、已有改动保护和结果验证规则。 + \item \textbf{上下文连续：}通过结构化、可版本管理的项目知识库保存长期有效信息。 +\end{itemize} + +\section{技术栈与运行环境} + +\begin{longtable}{p{0.23\textwidth}p{0.67\textwidth}} +\toprule +\textbf{组成} & \textbf{用途} \\ +\midrule +Markdown & 保存 Skill 主指令、README 和工作流参考文档。 \\ +YAML & \code{agents/openai.yaml} 保存显示名称、默认提示词和调用策略。 \\ +LaTeX & 提供可直接上传 Overleaf 的中文技术文档模板。 \\ +Cursor MDC & \code{.cursor/rules/karpathy-guidelines.mdc} 保存始终应用的编码行为规则。 \\ +EditorConfig & 统一字符编码、换行、缩进和行尾空格行为。 \\ +Git & 获取仓库状态，也是 \texttt{\$commit} 工作流的基础。 \\ +\bottomrule +\end{longtable} + +仓库自身没有包管理器、运行时依赖清单、编译脚本或自动测试入口。使用 Skill 需要一个能够从 \code{.agents/skills/} 发现项目级 Skill 的 AI 编码工具。生成的 LaTeX 文档默认面向 Overleaf 的 XeLaTeX 编译器。 + +\section{目录结构} + +\begin{lstlisting}[style=commandstyle] +Zero-DevToolbox/ +|-- .agents/ +| `-- skills/ +| |-- add-code-comments/ +| |-- commit/ +| |-- generate-latex-document/ +| | |-- agents/openai.yaml +| | |-- assets/document-template.tex +| | |-- references/codebase-workflow.md +| | |-- references/notes-workflow.md +| | `-- SKILL.md +| |-- init-project-knowledge/ +| |-- optimize-target-code/ +| |-- readme/ +| |-- reduce-code-redundancy/ +| |-- trace-code-flow/ +| `-- update-project-knowledge/ +|-- .cursor/rules/karpathy-guidelines.mdc +|-- ignore/ +| |-- .gitignore +| |-- .claudeignore +| `-- .cursorignore +|-- .editorconfig +|-- LICENSE +|-- README.md +`-- README_zh.md +\end{lstlisting} + +除 \code{generate-latex-document} 外，当前各 Skill 的核心结构是 \code{SKILL.md} 与 \code{agents/openai.yaml}。\code{generate-latex-document} 额外包含模板以及笔记整理、代码库说明两套工作流参考。 + +\section{总体架构} + +\subsection{分层组成} + +\begin{enumerate} + \item \textbf{发现与交互层：}\code{agents/openai.yaml} 提供显示名称、简短说明和默认提示词；所有现有 Skill 都设置 \code{allow_implicit_invocation: false}。 + \item \textbf{工作流定义层：}\code{SKILL.md} 描述适用场景、执行步骤、范围边界、安全规则和完成报告。 + \item \textbf{可选资源层：}复杂 Skill 可以通过 \code{references/} 拆分专项工作流，通过 \code{assets/} 保存可复用模板。 + \item \textbf{目标项目层：}Skill 被复制到目标仓库后，根据该项目的真实代码、配置、测试、Git 状态和文档执行。 + \item \textbf{配套规则层：}Cursor 规则、ignore 模板和 EditorConfig 为编码行为、上下文过滤和格式统一提供补充支持。 +\end{enumerate} + +\subsection{典型执行流程} + +\begin{enumerate} + \item 将完整 Skill 集合或选定目录复制到目标项目的 \code{.agents/skills/}。 + \item 在 AI 编码会话中使用 \texttt{\$skill-name} 显式调用所需工作流。 + \item Skill 读取目标项目适用的 \code{AGENTS.md}、相关代码、配置、测试和文档。 + \item Skill 确定处理范围，并避开第三方依赖、生成文件、缓存、日志和无关模块。 + \item 根据用户要求执行只读分析或小范围修改。 + \item 运行与风险相称的检查，并报告已验证结果、未验证内容及原有工作区改动。 +\end{enumerate} + +\begin{warningbox}{显式调用} +现有 9 个 Skill 均禁用隐式调用。自然语言任务不会自动授权这些工作流；使用者需要明确写出对应的 \texttt{\$skill-name}。 +\end{warningbox} + +\section{Skill 模块参考} + +\begin{longtable}{p{0.27\textwidth}p{0.63\textwidth}} +\toprule +\textbf{Skill} & \textbf{核心职责} \\ +\midrule +\texttt{\$add-code-comments} & 为用户指定的代码补充简洁、准确的变量和函数注释，并整理局部多余空行；只允许修改注释和空白格式，主要适用于支持 \code{//} 注释的语言。 \\ +\texttt{\$commit} & 检查 Git 工作区、暂存区、分支和远端，生成符合仓库风格的提交信息，并完成暂存、提交和推送。 \\ +\texttt{\$generate-latex-document} & 使用内置模板，将零散资料整理为技术文档，或分析代码库生成结构化说明；只输出独立的 \code{.tex} 文件。 \\ +\texttt{\$init-project-knowledge} & 首次分析现有项目，创建或完善 \code{AGENTS.md} 和结构化项目知识库，并使用真实代码与资料进行初步填充。 \\ +\texttt{\$optimize-target-code} & 优化指定函数、类、文件或小范围功能，关注效率、复杂度、数值稳定性、健壮性和可读性，并保持外部行为。 \\ +\texttt{\$readme} & 根据真实代码、配置、脚本和文档，同步创建、检查或更新英文 \code{README.md} 与中文 \code{README_zh.md}。 \\ +\texttt{\$reduce-code-redundancy} & 审计重复实现、未使用代码、冗余文件和分散工具；只清理证据充分且能够验证的候选项。 \\ +\texttt{\$trace-code-flow} & 只读追踪指定功能从入口到输出的调用链、数据流、状态变化、外部交互、单位和坐标系。 \\ +\texttt{\$update-project-knowledge} & 检查已完成工作，仅在产生经过确认且长期有效的信息时更新已有项目知识库。 \\ +\bottomrule +\end{longtable} + +\subsection{代码维护类工作流} + +\texttt{\$add-code-comments}、\texttt{\$optimize-target-code} 和 \texttt{\$reduce-code-redundancy} 共同覆盖可读性、局部实现质量与仓库级冗余治理。它们都强调限定范围、保留外部行为、避免顺带重构，并保护执行前已经存在的用户改动。 + +冗余清理支持 \code{mode=audit}（只分析）、\code{mode=apply}（清理已确认候选项）以及默认的“先审计、后确认”模式。 + +\subsection{理解与文档类工作流} + +\texttt{\$trace-code-flow} 用于建立从入口到输出的代码理解，重点区分接口、实现、调用者、动态路径、状态、副作用和数值约定。\texttt{\$readme} 将项目事实同步到中英文入口文档。\texttt{\$generate-latex-document} 则将笔记或代码库整理成适合交付的技术文档。 + +\subsection{Git 交付工作流} + +\texttt{\$commit} 会检查未暂存与已暂存差异、近期提交风格、当前分支和远端信息。其目标是根据实际 diff 生成提交信息，并安全完成提交和推送，而不是盲目提交整个工作区。 + +\section{项目知识库与上下文连续性} + +\subsection{初始化} + +\texttt{\$init-project-knowledge} 面向首次建立知识库的场景。它会检查现有 \code{AGENTS.md}、文档索引和已有知识文档，优先复用现有结构；缺少明确约定时，默认使用项目根目录下的 \code{docs/}。 + +知识库可以包含项目概览、架构、接口、技术决策、问题记录和当前进度。其目标是形成轻量、结构化、可版本管理、适合 Codex 长期使用的项目上下文。 + +\subsection{日常更新} + +\texttt{\$update-project-knowledge} 只更新已有知识库，不擅自创建新结构。它根据当前任务、Git 差异和验证结果，记录以后仍然有用的确认信息；普通聊天、临时想法、未验证猜测和冗长日志不会写入。 + +\subsection{解决的问题} + +这两个 Skill 形成“首次建立、按需维护”的生命周期，减少跨会话时项目目标、架构、接口、决策、已知问题和进度信息的丢失。这里的“知识库”是保存在项目文档中的版本化知识集合，不是数据库服务，也不引入额外运行时依赖。 + +\section{LaTeX 文档生成模块} + +\subsection{工作模式} + +\begin{itemize} + \item \textbf{笔记整理模式：}处理 Markdown、TXT、会议记录、学习笔记及其他零散资料。 + \item \textbf{代码库说明模式：}分析项目入口、核心模块、公共接口、配置、测试和主要流程。 +\end{itemize} + +两种模式分别读取 \code{references/notes-workflow.md} 和 \code{references/codebase-workflow.md}。除非用户明确要求混合生成，否则一次只使用一个工作流。 + +\subsection{模板与输出} + +\code{assets/document-template.tex} 提供 A4 页面、中文排版、页眉页脚、目录、代码块、表格和信息框样式。生成结果需要替换标题、副标题、项目名、作者、版本、封面说明和正文占位符，输出为不依赖 Skill 目录的完整 \code{.tex} 文件。 + +工作流不调用本地 LaTeX、XeLaTeX 或 \code{latexmk}，也不生成 PDF。结果默认上传 Overleaf 后使用 XeLaTeX 编译。 + +\section{安装与使用} + +\subsection{克隆仓库} + +\begin{lstlisting}[style=commandstyle] +git clone https://github.com/DreamCasterZero/Zero-DevToolbox.git +\end{lstlisting} + +\subsection{复制全部 Skill} + +macOS 或 Linux： + +\begin{lstlisting}[style=commandstyle] +mkdir -p /path/to/your-project/.agents +cp -R Zero-DevToolbox/.agents/skills /path/to/your-project/.agents/ +\end{lstlisting} + +PowerShell： + +\begin{lstlisting}[style=commandstyle] +New-Item -ItemType Directory -Force C:\path\to\your-project\.agents +Copy-Item -Recurse Zero-DevToolbox\.agents\skills C:\path\to\your-project\.agents\ +\end{lstlisting} + +\subsection{调用示例} + +\begin{lstlisting}[style=commandstyle] +$trace-code-flow trace the checkout flow from entry to output. +$reduce-code-redundancy mode=audit +$init-project-knowledge analyze this repository and build its knowledge base. +$readme synchronize the English and Chinese READMEs. +\end{lstlisting} + +\section{配套配置} + +\subsection{Cursor 行为规则} + +\code{.cursor/rules/karpathy-guidelines.mdc} 设置为 \code{alwaysApply: true}，要求编码前明确假设与权衡、优先使用最简单方案、只进行必要修改，以及用可验证目标驱动执行。 + +\subsection{Ignore 模板} + +\code{ignore/} 提供 \code{.gitignore}、\code{.claudeignore} 和 \code{.cursorignore}。规则覆盖密钥、依赖目录、构建和测试产物、日志、临时文件、数据库、媒体、IDE 元数据及工具缓存。 + +\begin{warningbox}{复制前检查} +默认 ignore 模板会排除锁文件和图片等内容，而部分项目应提交这些文件。复制后需要根据目标项目的版本控制策略检查并调整。 +\end{warningbox} + +\subsection{EditorConfig} + +\code{.editorconfig} 使用 UTF-8 和 LF，要求文件末尾换行，并为 Python、Web 与配置文件、Markdown、Makefile 和 Shell 脚本定义缩进及行尾空格策略。 + +\section{构建、运行与测试} + +Zero-DevToolbox 不包含可执行应用、包管理配置或自动测试脚本，因此不存在仓库级依赖安装、构建、启动和测试命令。文档中的复制命令来自当前 README；本次生成没有实际复制到其他项目，也没有执行网络克隆。 + +生成的本文档应上传 Overleaf，并选择 XeLaTeX 编译器。按照 Skill 约束，本次没有检查本地 LaTeX 环境，也没有执行编译或生成 PDF。 + +\section{常见问题} + +\begin{qabox}{可以只复制一个 Skill 吗？} +\end{qabox} +\begin{answerbox} +可以。每个 Skill 位于独立目录；复制时应保留其中的 \code{SKILL.md}、\code{agents/openai.yaml} 以及该 Skill 自带的 \code{assets/} 或 \code{references/}。 +\end{answerbox} + +\begin{qabox}{为什么 Skill 不会自动触发？} +\end{qabox} +\begin{answerbox} +当前所有 \code{agents/openai.yaml} 都设置 \code{allow_implicit_invocation: false}，使分析、修改、提交和知识库维护等工作流只能在用户明确授权后执行。 +\end{answerbox} + +\begin{qabox}{项目知识库是不是数据库？} +\end{qabox} +\begin{answerbox} +不是。它是由 \code{AGENTS.md}、文档索引及结构化 Markdown 文档组成的版本化知识集合，用于保存长期有效的项目上下文。 +\end{answerbox} + +\begin{qabox}{为什么没有类与函数参考？} +\end{qabox} +\begin{answerbox} +当前仓库以 Markdown、YAML、MDC 和 LaTeX 资源为主，不包含传统业务源码、类或公共函数，因此本文按 Skill 模块和工作流进行说明。 +\end{answerbox} + +\section{已知限制} + +\begin{itemize} + \item 实际可用性取决于宿主 AI 编码工具是否支持从 \code{.agents/skills/} 发现项目级 Skill。 + \item \texttt{\$add-code-comments} 主要面向支持 \code{//} 注释的语言。 + \item \texttt{\$generate-latex-document} 只生成 \code{.tex}，不负责本地编译、PDF 生成或 Overleaf 上传。 + \item 仓库没有自动化测试来验证 Skill 在不同宿主工具、操作系统和目标项目中的行为。 + \item 当前工作树包含尚未提交的配置迁移和 README 修改；本文描述当前文件状态，而不是最近一次提交的完整快照。 +\end{itemize} + +\section{许可证与来源} + +项目采用 MIT License，版权信息为 Copyright (c) 2026 DreamCasterZero。远端仓库地址为： + +\begin{center} +\url{https://github.com/DreamCasterZero/Zero-DevToolbox} +\end{center} + +本文内容依据当前仓库文件生成，未使用外部资料，也未推断未获支持的版本、性能或兼容性结论。 + + +\end{document} diff --git a/ignore/.claudeignore b/ignore/.claudeignore new file mode 100644 index 0000000..61d55c2 --- /dev/null +++ b/ignore/.claudeignore @@ -0,0 +1,96 @@ +# 密钥 & 凭据 +.env +.env.* +!.env.example +!.env.template +*.pem +*.key +*.p12 +*.jks +*.keystore +credentials.json +service-account.json +google-services.json +*-key.json +*_key.json + +# 依赖目录 +node_modules/ +.venv/ +venv/ +env/ +__pypackages__/ + +# 构建产物 +dist/ +build/ +out/ +target/ +__pycache__/ +*.py[cod] +*.so +*.egg-info/ +.next/ + +# 锁文件 +package-lock.json +yarn.lock +pnpm-lock.yaml +poetry.lock +Pipfile.lock + +# 测试 & 覆盖率 +coverage/ +.coverage +htmlcov/ +.pytest_cache/ +__snapshots__/ +.nyc_output/ + +# 日志 & 临时文件 +*.log +logs/ +tmp/ +temp/ +*.tmp +*.bak +*.swp +*~ + +# 数据库 +*.sqlite +*.sqlite3 +*.db +dump.sql + +# 二进制 & 媒体 +*.zip +*.tar.gz +*.rar +*.7z +*.mp4 +*.mov +*.mp3 +*.wav +*.png +*.jpg +*.jpeg +*.gif +*.webp + +# IDE & 系统文件 +.idea/ +.vscode/ +.DS_Store +Thumbs.db +.git/ + +# 工具缓存 +.cache/ +.mypy_cache/ +.ruff_cache/ +.ipynb_checkpoints/ + +# AI 工具 +.claude/sessions/ +.codex/log/ diff --git a/ignore/.cursorignore b/ignore/.cursorignore new file mode 100644 index 0000000..61d55c2 --- /dev/null +++ b/ignore/.cursorignore @@ -0,0 +1,96 @@ +# 密钥 & 凭据 +.env +.env.* +!.env.example +!.env.template +*.pem +*.key +*.p12 +*.jks +*.keystore +credentials.json +service-account.json +google-services.json +*-key.json +*_key.json + +# 依赖目录 +node_modules/ +.venv/ +venv/ +env/ +__pypackages__/ + +# 构建产物 +dist/ +build/ +out/ +target/ +__pycache__/ +*.py[cod] +*.so +*.egg-info/ +.next/ + +# 锁文件 +package-lock.json +yarn.lock +pnpm-lock.yaml +poetry.lock +Pipfile.lock + +# 测试 & 覆盖率 +coverage/ +.coverage +htmlcov/ +.pytest_cache/ +__snapshots__/ +.nyc_output/ + +# 日志 & 临时文件 +*.log +logs/ +tmp/ +temp/ +*.tmp +*.bak +*.swp +*~ + +# 数据库 +*.sqlite +*.sqlite3 +*.db +dump.sql + +# 二进制 & 媒体 +*.zip +*.tar.gz +*.rar +*.7z +*.mp4 +*.mov +*.mp3 +*.wav +*.png +*.jpg +*.jpeg +*.gif +*.webp + +# IDE & 系统文件 +.idea/ +.vscode/ +.DS_Store +Thumbs.db +.git/ + +# 工具缓存 +.cache/ +.mypy_cache/ +.ruff_cache/ +.ipynb_checkpoints/ + +# AI 工具 +.claude/sessions/ +.codex/log/ diff --git a/ignore/.gitignore b/ignore/.gitignore new file mode 100644 index 0000000..61d55c2 --- /dev/null +++ b/ignore/.gitignore @@ -0,0 +1,96 @@ +# 密钥 & 凭据 +.env +.env.* +!.env.example +!.env.template +*.pem +*.key +*.p12 +*.jks +*.keystore +credentials.json +service-account.json +google-services.json +*-key.json +*_key.json + +# 依赖目录 +node_modules/ +.venv/ +venv/ +env/ +__pypackages__/ + +# 构建产物 +dist/ +build/ +out/ +target/ +__pycache__/ +*.py[cod] +*.so +*.egg-info/ +.next/ + +# 锁文件 +package-lock.json +yarn.lock +pnpm-lock.yaml +poetry.lock +Pipfile.lock + +# 测试 & 覆盖率 +coverage/ +.coverage +htmlcov/ +.pytest_cache/ +__snapshots__/ +.nyc_output/ + +# 日志 & 临时文件 +*.log +logs/ +tmp/ +temp/ +*.tmp +*.bak +*.swp +*~ + +# 数据库 +*.sqlite +*.sqlite3 +*.db +dump.sql + +# 二进制 & 媒体 +*.zip +*.tar.gz +*.rar +*.7z +*.mp4 +*.mov +*.mp3 +*.wav +*.png +*.jpg +*.jpeg +*.gif +*.webp + +# IDE & 系统文件 +.idea/ +.vscode/ +.DS_Store +Thumbs.db +.git/ + +# 工具缓存 +.cache/ +.mypy_cache/ +.ruff_cache/ +.ipynb_checkpoints/ + +# AI 工具 +.claude/sessions/ +.codex/log/ diff --git a/zerotoolbox.pdf b/zerotoolbox.pdf new file mode 100644 index 0000000..fe4ba3f Binary files /dev/null and b/zerotoolbox.pdf differ