597 lines
22 KiB
TeX
597 lines
22 KiB
TeX
|
||
\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}
|