feat: add reusable engineering skill collection
This commit is contained in:
@@ -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 加一
|
||||
```
|
||||
@@ -0,0 +1,8 @@
|
||||
|
||||
interface:
|
||||
display_name: "补充代码注释"
|
||||
short_description: "为指定代码补充简洁注释并整理方法内部多余空行"
|
||||
default_prompt: "使用 $add-code-comments 为我指定的代码补充准确、简洁的中文注释，并整理局部多余空行。"
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
@@ -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
|
||||
```
|
||||
@@ -0,0 +1,7 @@
|
||||
interface:
|
||||
display_name: "提交 Git 改动"
|
||||
short_description: "检查当前仓库改动，生成提交信息并安全完成提交和推送"
|
||||
default_prompt: "使用 $commit 检查当前项目的 Git 改动，生成合适的提交信息并提交推送。"
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
@@ -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
|
||||
% _ & # $ { } ~ ^ \
|
||||
```
|
||||
@@ -0,0 +1,7 @@
|
||||
interface:
|
||||
display_name: "生成 LaTeX 技术文档"
|
||||
short_description: "使用内置模板整理笔记或生成结构化代码库说明文档"
|
||||
default_prompt: "使用 $generate-latex-document 根据输入资料或当前代码库生成完整的 LaTeX 技术文档。"
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
@@ -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}
|
||||
@@ -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
|
||||
文档概述
|
||||
项目简介
|
||||
技术栈与运行环境
|
||||
目录结构
|
||||
总体架构
|
||||
主要运行流程
|
||||
模块说明
|
||||
文件说明
|
||||
类与数据结构
|
||||
函数与接口参考
|
||||
配置参数
|
||||
构建、运行与测试
|
||||
常见问题
|
||||
已知限制
|
||||
```
|
||||
@@ -0,0 +1,54 @@
|
||||
# 笔记整理工作流
|
||||
|
||||
把 Markdown、TXT、会议记录、学习笔记和其他零散资料整理成结构化 LaTeX 文档。
|
||||
|
||||
## 确认输入
|
||||
|
||||
优先使用用户指定的文件或目录。
|
||||
|
||||
如果用户没有明确指定输入：
|
||||
|
||||
1. 检查当前任务中提到的 Markdown 和 TXT 文件；
|
||||
2. 如果只有少量明显相关的文件，列出并使用；
|
||||
3. 如果文件较多、主题不同或范围不明确，让用户选择；
|
||||
4. 不默认读取整个工作区。
|
||||
|
||||
记录实际读取的文件，不能只根据文件名猜测内容。
|
||||
|
||||
## 分析内容
|
||||
|
||||
提取并区分：
|
||||
|
||||
- 主题和目标；
|
||||
- 背景信息；
|
||||
- 核心概念；
|
||||
- 操作步骤；
|
||||
- 技术结论；
|
||||
- 问题和解决方法；
|
||||
- 决策和原因；
|
||||
- 待办事项；
|
||||
- 代码、命令、公式和数据；
|
||||
- 尚未确认的信息。
|
||||
|
||||
合并重复内容，但保留不同来源之间的重要差异。
|
||||
|
||||
发现矛盾时不要擅自选择结论，应明确标记冲突或“待确认”。
|
||||
|
||||
不要把聊天时间顺序直接当作文档结构。
|
||||
|
||||
## 组织文档
|
||||
|
||||
根据内容选择必要章节，可以采用：
|
||||
|
||||
```text
|
||||
文档概述
|
||||
背景与目标
|
||||
核心概念
|
||||
方案或处理流程
|
||||
实现与操作说明
|
||||
关键参数
|
||||
问题与解决方法
|
||||
结论
|
||||
待确认事项
|
||||
后续计划
|
||||
```
|
||||
@@ -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/
|
||||
```
|
||||
@@ -0,0 +1,7 @@
|
||||
interface:
|
||||
display_name: "初始化项目知识库"
|
||||
short_description: "分析现有项目并创建可长期维护的结构化知识库与导航规则"
|
||||
default_prompt: "使用 $init-project-knowledge 分析当前项目，并根据真实代码和资料建立项目知识库。"
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
@@ -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。
|
||||
|
||||
## 修改原则
|
||||
|
||||
默认保持以下内容不变：
|
||||
|
||||
- 公共接口和函数签名；
|
||||
- 输入输出含义；
|
||||
- 返回值和异常行为；
|
||||
- 状态修改和副作用；
|
||||
- 结果顺序和确定性；
|
||||
- 线程和异步语义；
|
||||
- 单位、坐标系、阈值和数值容差；
|
||||
- 配置和序列化兼容性。
|
||||
|
||||
如果优化需要更换算法，并且可能改变结果、精度或适用范围，先说明新旧方案和风险，获得用户确认后再修改。
|
||||
|
||||
不要：
|
||||
|
||||
- 顺便重构其他模块；
|
||||
- 格式化整个文件或项目；
|
||||
- 修改无关代码；
|
||||
- 为了减少代码行数而过度抽象；
|
||||
- 在没有测量时声称性能已经提升；
|
||||
- 为通过测试而降低断言标准；
|
||||
- 覆盖或回退用户原有改动。
|
||||
|
||||
## 性能验证
|
||||
|
||||
只有用户关注性能，或者修改明显针对性能时才进行基准测量。
|
||||
|
||||
优化前后使用相同输入、环境和构建模式，并重复运行。无法可靠测量时，只说明理论复杂度和预期收益，不声称实际性能提升。
|
||||
|
||||
## 特殊情况
|
||||
|
||||
对于数学、机器人、控制和实时代码，重点检查浮点误差、单位、坐标系、采样周期、角度归一化、饱和处理和实时周期，不擅自修改公式或参数。
|
||||
|
||||
硬件控制、部署和实机测试需要用户明确授权。
|
||||
|
||||
## 完成报告
|
||||
|
||||
简要报告：
|
||||
|
||||
- 优化了哪个文件或函数；
|
||||
- 发现了什么问题；
|
||||
- 做了什么修改；
|
||||
- 复杂度或预期收益；
|
||||
- 执行了哪些测试或构建；
|
||||
- 哪些内容尚未验证。
|
||||
|
||||
如果没有值得实施的安全优化，明确说明，不要强行修改代码。
|
||||
@@ -0,0 +1,8 @@
|
||||
|
||||
interface:
|
||||
display_name: "优化指定代码"
|
||||
short_description: "分析并优化指定函数或文件，并用测试和基准验证改进效果"
|
||||
default_prompt: "使用 $optimize-target-code 分析指定函数或文件，建立基线并实施可验证的最小优化。"
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
@@ -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. 确认没有修改其他文件。
|
||||
@@ -0,0 +1,7 @@
|
||||
interface:
|
||||
display_name: "维护中英文 README"
|
||||
short_description: "根据项目真实内容同步创建或更新中英文 README"
|
||||
default_prompt: "使用 $readme 根据当前项目的真实代码和配置，同步创建或更新英文 README.md 与中文 README_zh.md。"
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
@@ -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 状态
|
||||
当前分支
|
||||
构建方式
|
||||
测试方式
|
||||
已有静态检查工具
|
||||
当前构建和测试结果
|
||||
```
|
||||
@@ -0,0 +1,8 @@
|
||||
|
||||
interface:
|
||||
display_name: "清理代码库冗余"
|
||||
short_description: "审计重复实现和无效代码，并安全清理已充分确认的冗余内容"
|
||||
default_prompt: "使用 $reduce-code-redundancy 审计当前代码库，并在充分验证后清理能够确认的冗余内容。"
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
@@ -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
|
||||
## 目标
|
||||
|
||||
功能、入口以及分析范围。
|
||||
|
||||
## 调用链
|
||||
|
||||
入口方法
|
||||
→ 中间方法
|
||||
→ 核心实现
|
||||
→ 输出方法
|
||||
|
||||
每一步标注对应文件和符号。
|
||||
|
||||
## 数据流
|
||||
|
||||
| 阶段 | 输入 | 处理 | 输出 | 单位/坐标系 |
|
||||
|---|---|---|---|---|
|
||||
|
||||
## 状态变化
|
||||
|
||||
| 位置 | 状态 | 变化 | 影响 |
|
||||
|---|---|---|---|
|
||||
|
||||
没有状态变化时明确说明。
|
||||
|
||||
## 分支与异常路径
|
||||
|
||||
说明关键条件分支、提前返回、异常处理和失败结果。
|
||||
|
||||
## 最终输出
|
||||
|
||||
说明最终返回值、发送消息、文件写入或硬件指令。
|
||||
|
||||
## 待确认
|
||||
|
||||
列出无法通过静态代码确定的信息。
|
||||
```
|
||||
@@ -0,0 +1,8 @@
|
||||
|
||||
interface:
|
||||
display_name: "追踪代码流程"
|
||||
short_description: "快速分析指定功能的调用链、数据流、状态和单位"
|
||||
default_prompt: "使用 $trace-code-flow 追踪我指定功能从入口到最终输出的完整代码流程。"
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
@@ -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. 工作区中是否存在执行前就已经存在的其他改动。
|
||||
@@ -0,0 +1,7 @@
|
||||
interface:
|
||||
display_name: "更新项目知识库"
|
||||
short_description: "检查本次工作并按需更新项目中长期有效的结构化知识文档"
|
||||
default_prompt: "使用 $update-project-knowledge 检查本次项目工作，并仅在必要时更新已有知识库。"
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
Reference in New Issue
Block a user