名称: ai-factory.docs 描述: 生成和维护项目文档。创建一个简洁的README作为着陆页，并带有按主题分割的详细文档目录。当用户说“创建文档”、“编写文档”、“更新文档”、“生成README”或“文档项目”时使用。 参数提示: “[–web]” 允许工具: 读取 写入 编辑 全局查找 搜索 Bash(mkdir, npx, python) 询问用户问题 问题 网页获取 网页搜索 禁用模型调用: true 元数据: 作者: AI Factory 版本: “1.0” 类别: 文档
文档 - 项目文档生成器
生成、维护和改进项目文档，遵循着陆页README + 详细文档/结构。
核心原则
- README是着陆页，不是手册。 ~80-120行。第一印象、安装、快速示例、链接到详情。
- 详情放入
docs/。 每个文件自包含 — 一个主题，一页。用户应该能够阅读单个文档文件并获得该主题的完整图片。 - 无重复。 如果信息在
docs/中，README链接到它 — 不重复它。例外：安装命令可以出现在两者中（用户期望在README中）。 - 导航。 每个docs/文件都有一个标题行，带有prev/next链接，遵循文档表格顺序：
[← 上一页](prev.md) · [返回README](../README.md) · [下一页 →](next.md)。第一页没有prev链接；最后一页没有next链接。每页以“另请参阅”部分结束，链接到2-3个相关页面。 - 交叉链接使用相对路径。 从README：
docs/workflow.md。docs之间：workflow.md（相同目录）。 - 可扫描。 使用表格、项目列表和代码块。避免长段落。用户扫描，不阅读。
工作流程
步骤 0: 加载项目上下文
读取.ai-factory/DESCRIPTION.md 如果存在以理解：
- 技术栈（语言、框架、数据库）
- 项目目的和架构
- 关键功能和约定
探索代码库：
- 读取
package.json、composer.json、requirements.txt、go.mod、Cargo.toml等。 - 扫描
src/结构以理解架构 - 查找现有文档、注释、API端点、CLI命令
- 检查现有README.md和docs/目录
扫描项目根目录中分散的markdown文件：
使用Glob查找项目根目录中所有*.md文件（排除node_modules/、.ai-factory/、代理目录）：
CHANGELOG.md, CONTRIBUTING.md, ARCHITECTURE.md, DEPLOYMENT.md,
SECURITY.md, API.md, SETUP.md, DEVELOPMENT.md, TESTING.md, 等。
记录每个文件、其大小和内容简要摘要。此列表用于步骤1.1。
步骤 0.1: 解析标志
--web → 生成文档的HTML版本
步骤 1: 确定当前状态
检查现有文档：
状态 A: 无 README.md → 完整生成（README + docs/）
状态 B: README.md 存在，无 docs/ → 分析README，建议分割到docs/
状态 C: README.md + docs/ 存在 → 取决于标志（见下文）
状态 C 带有 --web 标志 — 询问用户：
文档已存在（README.md + docs/）。
您想做什么？
- [ ] 仅生成HTML — 从当前文档构建站点
- [ ] 先审核和改进 — 检查问题，然后生成HTML
- [ ] 仅审核 — 检查问题而不生成HTML
- “仅生成HTML” → 跳过步骤1.1、步骤2、步骤4 — 直接到步骤3（HTML生成），然后完成
- “先审核和改进” → 运行步骤1.1 → 步骤2（状态 C） → 步骤3 → 步骤4 → 步骤4.1
- “仅审核” → 运行步骤1.1 → 步骤2（状态 C） → 步骤4 → 步骤4.1（跳过步骤3）
状态 C 无 --web 标志 → 正常运行步骤2（状态 C）。
步骤 1.1: 检查分散的Markdown文件
如果在项目根目录中找到分散的.md文件（从步骤0），建议将它们整合到docs/目录。
应移动到docs/的常见文件：
| 根文件 | 目标在 docs/ | 合并或移动？ |
|---|---|---|
CONTRIBUTING.md |
docs/contributing.md |
移动 |
ARCHITECTURE.md |
docs/architecture.md |
移动 |
DEPLOYMENT.md |
docs/deployment.md |
移动 |
SETUP.md |
docs/getting-started.md |
合并（追加到现有） |
DEVELOPMENT.md |
docs/getting-started.md 或 docs/contributing.md |
合并 |
API.md |
docs/api.md |
移动 |
TESTING.md |
docs/testing.md |
移动 |
SECURITY.md |
docs/security.md |
移动 |
留在根目录的文件（标准约定）：
README.md— 总是保留CHANGELOG.md— 标准根级文件，保持原样LICENSE/LICENSE.md— 标准根级文件，保持原样CODE_OF_CONDUCT.md— 标准根级文件，保持原样
如果找到分散文件，询问用户：
在项目根目录中找到 [N] 个markdown文件：
CONTRIBUTING.md (45行) — 贡献指南
ARCHITECTURE.md (120行) — 系统架构概述
DEPLOYMENT.md (80行) — 部署说明
SETUP.md (30行) — 设置指南（与getting-started重叠）
建议操作：
→ 移动 CONTRIBUTING.md → docs/contributing.md
→ 移动 ARCHITECTURE.md → docs/architecture.md
→ 移动 DEPLOYMENT.md → docs/deployment.md
→ 合并 SETUP.md 到 docs/getting-started.md
您想：
- [ ] 应用所有建议
- [ ] 让我选择哪些
- [ ] 跳过 — 保持文件原样
当移动/合并时：
- 在
docs/中创建目标文件，带有prev/next导航标题（遵循文档表格顺序）和“另请参阅”页脚 - 如果合并到现有文档 — 在新部分标题下追加内容，避免重复已存在的信息
- 暂时不要删除原始文件 — 在审核步骤确认一切就位前保留它们
- 将新docs/页面添加到README的文档表格中
- 更新其他文件中指向旧根级文件的任何链接
- 记录哪些文件被移动/合并 — 此列表用于步骤4.1
重要： 从不强制移动文件。总是先显示计划并获取用户批准。
步骤 2 (状态 A): 从零开始生成
当无 README.md 存在时，生成完整文档集。
2.1: 分析项目以获取文档主题
探索代码库并识别文档主题：
始终包括：
- getting-started.md （安装、设置、快速开始）
如果相关则包括：
- architecture.md （如果项目有清晰架构：服务、模块、层）
- api.md （如果项目暴露API端点）
- configuration.md （如果项目有配置文件、环境变量、功能标志）
- deployment.md （如果Dockerfile、CI/CD、部署脚本存在）
- contributing.md （如果开源或团队项目）
- security.md （如果身份验证、权限或安全模式存在）
- testing.md （如果测试套件存在）
- cli.md （如果项目有CLI命令）
询问用户：
我分析了您的项目并建议这些文档页面：
1. getting-started.md — 安装、设置、快速开始
2. architecture.md — 项目结构和模式
3. api.md — API端点参考
4. configuration.md — 环境变量和配置
您想：
- [ ] 生成所有这些
- [ ] 让我选择哪些
- [ ] 添加更多主题
2.2: 生成 README.md
结构（目标~80-120行）：
# 项目名称
> 一行标语描述项目。
2-3句简要描述项目做什么以及为什么存在。
## 快速开始
\`\`\`bash
# 安装步骤（1-3个命令）
\`\`\`
## 关键功能
- **功能 1** — 简要描述
- **功能 2** — 简要描述
- **功能 3** — 简要描述
## 示例
\`\`\`
# 显示真实使用示例 — 这是用户决定“我想要这个”的地方
\`\`\`
---
## 文档
| 指南 | 描述 |
|-------|-------------|
| [快速开始](docs/getting-started.md) | 安装、设置、第一步 |
| [架构](docs/architecture.md) | 项目结构和模式 |
| [API参考](docs/api.md) | 端点、请求/响应格式 |
| [配置](docs/configuration.md) | 环境变量、配置文件 |
## 许可证
MIT（或项目中的任何内容）
README的关键规则：
- 顶部徽标/徽章行（如果项目有）
- 标语作为块引用
- 快速开始带有真实安装命令（从包管理器检测）
- 关键功能作为项目列表（3-6项，可扫描）
- 真实使用示例显示“哇因素”
- 文档表格链接到docs/
- 底部许可证
- 无长描述、无完整API参考、无配置详情
2.3: 生成 docs/ 文件
对于每个批准的主题，创建文档文件：
[← 上一主题](previous-topic.md) · [返回README](../README.md) · [下一主题 →](next-topic.md)
# 主题标题
内容按子主题组织，带有标题、代码示例和表格。
保持每个部分自包含。
## 另请参阅
- [相关主题 1](related-topic.md) — 简要描述
- [相关主题 2](other-topic.md) — 简要描述
导航链接顺序 遵循README.md中的文档表格（从上到下）。第一文档页省略“← 上一”链接；最后一页省略“下一 →”链接。示例4页：
getting-started.md: [返回README](../README.md) · [架构 →](architecture.md)
architecture.md: [← 快速开始](getting-started.md) · [返回README](../README.md) · [API参考 →](api.md)
api.md: [← 架构](architecture.md) · [返回README](../README.md) · [配置 →](configuration.md)
configuration.md: [← API参考](api.md) · [返回README](../README.md)
每个主题的内容指南：
- 先决条件（运行时版本、所需工具）
- 逐步安装
- 首次运行 / 快速开始
- 验证工作（预期输出）
- 下一步链接
- 高级概述（如果有用则用图表）
- 目录结构带解释
- 关键模式（命名、导入、错误处理）
- 数据流
- 基本URL / 配置
- 身份验证
- 按资源分组的端点
- 请求/响应示例
- 错误代码
- 所有环境变量带描述和默认值
- 配置文件及其目的
- 功能标志
- 构建步骤
- 环境设置
- CI/CD流水线描述
- 监控 / 健康检查
步骤 2 (状态 B): 将现有README分割到docs/
当README.md存在但长（150+行）且无docs/目录时。
2.1: 分析README结构
读取README.md并识别：
- 哪些部分应保留（着陆页内容）
- 哪些部分应移动到docs/（详细内容）
保留在README：
- 标题、标语、徽章
- “为什么？” / 关键功能项目列表
- 快速安装（1-3个命令）
- 简要示例
- 文档链接表格
- 外部链接、许可证
移动到docs/：
- 详细设置说明 →
getting-started.md - 架构 / 项目结构 →
architecture.md - 完整API参考 →
api.md - 配置详情 →
configuration.md - 贡献指南 →
contributing.md - 任何覆盖单个主题且长~30行的部分
2.2: 向用户提议更改
您的README.md是 [N] 行。我建议分割它：
README.md (~100行) — 保留为着陆页：
✓ 标题 + 标语
✓ 关键功能
✓ 快速安装
✓ 示例
✓ 文档链接表格
移动到 docs/：
→ “安装”部分 → docs/getting-started.md
→ “配置”部分 → docs/configuration.md
→ “API参考”部分 → docs/api.md
→ “架构”部分 → docs/architecture.md
继续？
2.3: 执行分割
- 创建
docs/目录 - 创建每个文档文件，内容来自README + prev/next导航标题（遵循文档表格顺序）+ “另请参阅”页脚
- 重写README作为着陆页，带有文档链接表格
- 验证无内容丢失 — 旧README的每个部分必须存在于某处
步骤 2 (状态 C): 改进现有文档
当README.md和docs/都存在时。
2.1: 审核当前文档
检查：
- README长度 — 是否仍是着陆页（<150行）？
- 缺失主题 — 是否有项目方面未文档化？
- 过时内容 — 文档是否引用不再存在的文件/API？
- 导航 — 所有文档是否有prev/next标题链接和“另请参阅”？
- 坏链接 — 验证所有内部链接指向现有文件/锚点
- 一致性 — 所有文档中相同的格式样式
- 标准合规性 — 现有文档是否符合当前技能标准？（见2.1.1）
2.1.1: 标准合规性检查
文档可能由旧版本的此技能生成。比较现有文档与当前核心原则和模板。常见差距检测：
| 缺失标准 | 如何检测 | 自动修复 |
|---|---|---|
| 无prev/next导航 | 标题只有[← 返回README]无·链接到兄弟页面 |
添加prev/next链接遵循文档表格顺序 |
| 无“另请参阅”部分 | 文件以无## 另请参阅结束 |
添加部分带2-3个相关页面链接 |
| 旧“返回README”格式 | 链接路径或文本不匹配当前模式 | 更新到当前格式 |
| README中缺失文档表格 | README无表格链接到docs/页面 | 添加表格 |
| README太长 | README超过150行尽管docs/存在 | 提议移动多余内容到docs/ |
当找到差距时，将它们包含在审核报告中与内容问题一起（步骤2.2）。将其视为常规改进 — 显示计划并在应用前获取用户批准。
不要问“这是由旧版本生成的吗？” — 只是静默检测缺失并修复。用户不需要知道技能版本；他们只看到文档变好。
2.2: 提议改进
文档审核结果：
✅ README是简洁的（105行）
⚠️ docs/页面缺失prev/next导航 — 将添加
⚠️ docs/api.md缺失 — 项目有12个API端点
⚠️ docs/configuration.md引用旧环境变量DB_HOST（现在DATABASE_URL）
❌ docs/getting-started.md链接到docs/setup.md，后者不存在
提议修复：
1. 添加prev/next导航到所有docs/页面
2. 创建docs/api.md带端点参考
3. 更新docs/configuration.md中的DATABASE_URL
4. 修复docs/getting-started.md中的坏链接
应用修复？
步骤 3: 生成HTML版本 (–web 标志)
当传递 --web 标志时，从markdown文档生成静态HTML站点。
3.1: 创建 docs-html/ 目录
mkdir -p docs-html
3.2: 生成HTML文件
对于每个markdown文件（README.md + docs/*.md），生成HTML版本：
HTML模板：
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{page_title} — {project_name}</title>
<style>
:root {
--bg: #ffffff;
--text: #1a1a2e;
--text-secondary: #555;
--accent: #0066cc;
--border: #e2e8f0;
--code-bg: #f6f8fa;
--nav-bg: #f8fafc;
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #0d1117;
--text: #e6edf3;
--text-secondary: #8b949e;
--accent: #58a6ff;
--border: #30363d;
--code-bg: #161b22;
--nav-bg: #161b22;
}
}
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
line-height: 1.6;
color: var(--text);
background: var(--bg);
max-width: 900px;
margin: 0 auto;
padding: 2rem 1.5rem;
}
nav {
background: var(--nav-bg);
border: 1px solid var(--border);
border-radius: 8px;
padding: 1rem 1.5rem;
margin-bottom: 2rem;
}
nav a {
color: var(--accent);
text-decoration: none;
margin-right: 1.5rem;
}
nav a:hover { text-decoration: underline; }
nav a.active { font-weight: 600; }
h1 { font-size: 2rem; margin: 1.5rem 0 1rem; border-bottom: 2px solid var(--border); padding-bottom: 0.5rem; }
h2 { font-size: 1.5rem; margin: 2rem 0 0.75rem; }
h3 { font-size: 1.2rem; margin: 1.5rem 0 0.5rem; }
p { margin: 0.75rem 0; }
a { color: var(--accent); }
code {
background: var(--code-bg);
padding: 0.15em 0.4em;
border-radius: 4px;
font-size: 0.9em;
}
pre {
background: var(--code-bg);
border: 1px solid var(--border);
border-radius: 8px;
padding: 1rem;
overflow-x: auto;
margin: 1rem 0;
}
pre code { background: none; padding: 0; }
table {
width: 100%;
border-collapse: collapse;
margin: 1rem 0;
}
th, td {
border: 1px solid var(--border);
padding: 0.5rem 0.75rem;
text-align: left;
}
th { background: var(--code-bg); font-weight: 600; }
ul, ol { padding-left: 1.5rem; margin: 0.75rem 0; }
li { margin: 0.25rem 0; }
blockquote {
border-left: 4px solid var(--accent);
padding-left: 1rem;
color: var(--text-secondary);
margin: 1rem 0;
}
hr { border: none; border-top: 1px solid var(--border); margin: 2rem 0; }
img { max-width: 100%; border-radius: 8px; }
</style>
</head>
<body>
<nav>
{nav_links}
</nav>
<main>
{content}
</main>
</body>
</html>
3.3: 转换markdown到HTML
对于每个文档文件：
- 解析markdown内容（标题、代码块、表格、链接、列表、块引用、图像）
- 转换为HTML元素
- 修复链接： 更改
.md引用为.html（例如，docs/getting-started.md→getting-started.html） - 生成导航栏，链接到所有页面
- 写入
docs-html/目录
文件映射：
README.md → docs-html/index.html
docs/getting-started.md → docs-html/getting-started.html
docs/api.md → docs-html/api.html
docs/configuration.md → docs-html/configuration.html
3.4: 输出结果
✅ HTML文档生成在 docs-html/
docs-html/
├── index.html （来自 README.md）
├── getting-started.html （来自 docs/getting-started.md）
├── api.html （来自 docs/api.md）
└── configuration.html （来自 docs/configuration.md）
在浏览器中打开：
open docs-html/index.html
步骤 4: 文档审核
任何内容更改后强制进行（生成、分割、改进、文件整合）。不要跳过此步骤。
仅当选择“仅生成HTML”时跳过此步骤 — 无内容修改，无需审核。
读取每个生成/修改的文件并针对以下两个检查表评估它。在向用户呈现结果前修复任何找到的问题。
技术检查表
验证结构、链接和完整性：
- [ ] README.md 少于150行
- [ ] README有：标题、标语、快速开始、示例、文档表格、许可证
- [ ] 每个docs/文件有prev/next导航标题遵循文档表格顺序
- [ ] 第一文档页无“← 上一”链接；最后一页无“下一 →”链接
- [ ] 每个docs/文件底部有“另请参阅”部分带2-3个相关链接
- [ ] 分割/重组期间无内容丢失
- [ ] 所有内部链接工作（无坏引用、无死锚点）
- [ ] 代码示例使用项目的实际命令/语法
- [ ] 安装说明真实且工作（从包管理器文件验证）
- [ ] README和docs/之间无重复内容
- [ ] 无分散根级
.md文件应放docs/
可读性检查表 — “新用户视角”
读取每页，仿佛您是从未见过此项目的开发人员。对于每页，验证：
前10秒（首屏）：
- [ ] 我能在阅读README的10秒内理解此项目做什么吗？
- [ ] 标语清晰具体 — 不模糊营销（“下一代解决方案”）？
- [ ] 有真实的安装命令我可以立即复制粘贴吗？
“展示，不讲述”：
- [ ] README有具体使用示例（不仅仅是“安装并运行”）？
- [ ] 代码块显示真实命令与真实输出，不是抽象占位符？
- [ ] 示例可复制粘贴 — 无
<placeholder>用户必须替换？
可扫描性：
- [ ] 我能在5秒内通过扫描标题找到任何特定主题吗？
- [ ] 段落短（最大3-4行）？长段落被跳过
- [ ] 使用列表而不是逗号分隔的内联枚举？
- [ ] 使用表格处理结构化数据而不是嵌套项目列表？
行话和假设：
- [ ] 文档页在首次使用时解释缩写（或链接到解释）？
- [ ] 无关于内部知识的假设？（“如RFC中描述” — 哪个RFC？）
- [ ] 初级开发人员能在不问同事的情况下理解每页吗？
导航和流程：
- [ ] 阅读README后，清楚下一步去哪里吗？
- [ ] 完成任何docs/页后，prev/next链接和“另请参阅”逻辑上引导我前进吗？
- [ ] README中的文档表格按新用户会遵循的路径排序吗？（快速开始 → 工作流程 → 详情）
动机：
- [ ] README在“如何工作”前回答“为什么我应该关心？”吗？
- [ ] 有“哇时刻” — 让我想尝试的功能或示例吗？
- [ ] 文档结构感觉邀请，不压倒吗？（最大6-8文档页）
呈现审核
运行两个检查表后，呈现摘要：
📋 文档审核
技术：
✅ 所有链接已验证（14个内部链接，0个坏）
✅ README是108行
✅ 所有页面有导航
⚠️ docs/api.md有占位符示例 — 需要真实端点
可读性：
✅ README在10秒内解释目的
✅ 所有代码示例可复制粘贴
⚠️ docs/architecture.md有12行段落 — 应分割
⚠️ “CQRS”在docs/architecture.md中使用未解释
应用修复：
→ 分割docs/architecture.md中的长段落为3个较短段落
→ 添加“（命令查询责任隔离）”在首次提及CQRS后
→ 替换docs/api.md中的占位符为真实端点示例
所有检查通过 ✅
步骤 4.1: 清理移动文件
仅如果在步骤1.1期间文件从根移动到docs/。
审核确认所有内容正确放置在docs/后，提供删除原始根级文件：
以下根文件已纳入 docs/：
CONTRIBUTING.md → 现在在 docs/contributing.md
ARCHITECTURE.md → 现在在 docs/architecture.md
DEPLOYMENT.md → 现在在 docs/deployment.md
SETUP.md → 合并到 docs/getting-started.md
这些原始文件不再需要。删除它们？
- [ ] 是，删除所有原始文件
- [ ] 让我选择哪些删除
- [ ] 否，保留它们（我稍后清理）
当删除时：
- 再次验证目标docs/文件包含原始的所有内容
- 删除根文件
- 运行
git status显示删除了什么 — 用户可以用git checkout恢复如果需要
不要自动删除。 总是询问。用户可能想暂时保留原始文件以供参考或差异比较。
步骤 5: 更新 AGENTS.md
任何文档更改后，更新AGENTS.md中的文档部分（如果文件存在）。
读取AGENTS.md并找到## 文档部分。更新它以反映所有文档文件的当前状态：
## 文档
| 文档 | 路径 | 描述 |
|----------|------|-------------|
| README | README.md | 项目着陆页 |
| 快速开始 | docs/getting-started.md | 安装、设置、第一步 |
| 架构 | docs/architecture.md | 项目结构和模式 |
| API参考 | docs/api.md | 端点、请求/响应格式 |
| 配置 | docs/configuration.md | 环境变量、配置文件 |
规则：
- 首先列出README.md，然后所有docs/文件按README文档表格顺序
- 如果在步骤1.1期间文件从根移动/合并，反映新位置
- 如果创建了新文档页，添加它们
- 如果文档页被移除，移除它们
- 保持描述简洁（少于10词）
- 如果
AGENTS.md不存在，静默跳过此步骤
上下文清理
代码库扫描和文档生成后上下文重。所有文档已保存 — 建议释放空间：
询问用户问题：继续前释放上下文？
选项：
1. /clear — 完全重置（推荐）
2. /compact — 压缩历史
3. 继续原样
重要规则
- 总是先询问再更改现有文档 — 先显示计划
- 从不删除内容 而不移动到别处
- 检测真实项目信息 — 不发明功能，读取package.json/配置文件
- 使用项目的语言 — 如果项目README是俄语，用俄语写文档
- 保留现有徽章/徽标 — 不在重组期间移除它们
- 添加到 .gitignore 如果生成HTML：添加
docs-html/到 .gitignore