القائمة
代码库文档生成器 - 适用于为代码库编写文档，包括README文件、架构文档、代码注释和API文档。当用户请求帮助记录代码、创建入门指南、解释项目结构或使代码库对新开发者更友好时使用此技能。该技能提供模板、最佳实践和结构化方法来创建清晰、适合初学者的文档。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
设置并使用 1Password CLI (op)。在安装 CLI、启用桌面应用集成、登录（单个或多个帐户）或通过 op 读取/注入/运行密钥时使用。
停止等待提示词，让工作继续进行。
Agent 体验守护系统。解决AI助手常见体验问题 ：长时间无响应、任务卡死、中英文混用、状态不透明。包含看门狗监控、智能状态汇报、即时状态查询、语言一致性过滤、消息队列追踪。适用于所有渠道 （ QQ微信//Telegram飞书//Discord等 ）。当用户抱怨等太久没回复、 “回复中英文混着”、 “不知道在干什么”时使用此技能。
针对 AI 代理 (Agent) 失败的结构化自调试工作流，包括捕捉、诊断、受控恢复和内省报告。
AI 代理的记忆管理工具 - 列表显示、搜索查找、摘要生成及记忆文件维护。包含 AI 驱动的摘要功能。
Optimize multi-agent systems with coordinated profiling, workload distribution, and cost-aware orchestration. Use when improving agent performance, throughput, or reliability.
استنادا إلى تصنيف SOC المهني
| name | codebase-documenter |
| description | 代码库文档生成器 - 适用于为代码库编写文档，包括README文件、架构文档、代码注释和API文档。当用户请求帮助记录代码、创建入门指南、解释项目结构或使代码库对新开发者更友好时使用此技能。该技能提供模板、最佳实践和结构化方法来创建清晰、适合初学者的文档。 |
本技能用于为代码库创建全面的、对初学者友好的文档。它提供了结构化的模板和最佳实践，用于编写 README、架构指南、代码注释和 API 文档，帮助新用户快速理解项目并为项目做出贡献。
在为新用户记录代码时，请遵循以下基本原则：
何时创建： 用于项目根目录、主要功能模块或独立组件。
遵循的结构：
# 项目名称
## 这是什么
[1-2 句话的通俗解释]
## 快速开始
[让用户在 < 5 分钟内运行项目]
## 项目结构
[带有解释的可视化文件树]
## 核心概念
[用户需要理解的核心概念]
## 常见任务
[常见操作的逐步指南]
## 故障排除
[常见问题和解决方案]
最佳实践：
何时创建： 用于具有多个模块、复杂数据流或非显而易见的设计决策的项目。
遵循的结构：
# 架构概述
## 系统设计
[高级图表和解释]
## 目录结构
[每个目录用途的详细说明]
## 数据流
[数据如何在系统中流动]
## 关键设计决策
[为什么做出某些架构选择]
## 模块依赖
[不同部分如何交互]
## 扩展点
[在哪里以及如何添加新功能]
最佳实践：
何时创建： 用于复杂逻辑、不明显的算法或需要上下文的代码。
注释模式：
函数/方法文档：
/**
* 计算部分计费周期的按比例订阅费用。
*
* 为什么存在：用户可以在月中订阅，因此我们只需要
* 向他们收取当前计费周期剩余天数的费用。
*
* @param {number} fullPrice - 正常的月度订阅价格
* @param {Date} startDate - 用户订阅的开始日期
* @param {Date} periodEnd - 当前计费周期的结束日期
* @returns {number} 按比例计算的金额
*
* @example
* // 用户在 1 月 15 日订阅，周期在 1 月 31 日结束
* calculateProratedCost(30, new Date('2024-01-15'), new Date('2024-01-31'))
* // 返回：16.13（31 天中的 17 天）
*/
复杂逻辑文档：
# 为什么需要这个检查：API 对已删除的用户返回 null，
# 但对从未设置名称的用户返回空字符串。我们需要
# 在审计日志中区分这些情况。
if user_name is None:
# 用户已被删除 - 将此记录为安全事件
log_deletion_event(user_id)
elif user_name == "":
# 用户从未完成注册 - 可以安全跳过
continue
最佳实践：
何时创建： 用于任何 HTTP 端点、SDK 方法或公共接口。
遵循的结构：
## 端点名称
### 功能
[端点功能的通俗解释]
### 端点
`POST /api/v1/resource`
### 身份验证
[需要什么认证以及如何提供]
### 请求格式
[JSON 模式或示例请求]
### 响应格式
[JSON 模式或示例响应]
### 使用示例
[带有 curl/代码的具体示例]
### 常见错误
[错误代码及其含义]
### 相关端点
[链接到相关操作]
最佳实践：
在编写文档之前：
根据用户请求和代码库分析：
使用 assets/templates/ 中的模板作为起点：
assets/templates/README.template.md - 用于项目 READMEassets/templates/ARCHITECTURE.template.md - 用于架构文档assets/templates/API.template.md - 用于 API 文档根据具体代码库自定义模板：
在完成文档之前：
本技能在 assets/templates/ 中包含几个模板作为起点：
assets/templates/ 阅读相应模板有关详细的文档最佳实践、样式指南和高级模式，请参阅：
references/documentation_guidelines.md - 综合样式指南和最佳实践references/visual_aids_guide.md - 如何创建有效的图表和文件树在以下情况下加载这些参考：
文件树帮助新用户理解项目组织：
project-root/
├── src/ # 源代码
│ ├── components/ # 可复用的 UI 组件
│ ├── pages/ # 页面级组件（路由）
│ ├── services/ # 业务逻辑和 API 调用
│ ├── utils/ # 辅助函数
│ └── types/ # TypeScript 类型定义
├── public/ # 静态资源（图片、字体）
├── tests/ # 测试文件，镜像 src 结构
└── package.json # 依赖和脚本
使用带图表的编号步骤：
用户请求流：
1. 用户提交表单 → 2. 验证 → 3. API 调用 → 4. 数据库 → 5. 响应
[1] components/UserForm.tsx
↓ 验证输入
[2] services/validation.ts
↓ 发送到 API
[3] services/api.ts
↓ 查询数据库
[4] 数据库（PostgreSQL）
↓ 返回数据
[5] components/UserForm.tsx（更新 UI）
捕捉架构选择背后的“为什么”：
## 为什么我们使用 Redux
**决策：** 使用 Redux 进行状态管理而不是 Context API
**背景：** 我们的应用有 50+ 个组件需要访问用户
认证状态、购物车和 UI 偏好。
**推理：**
- 上下文 API 会导致这么多组件不必要的重新渲染
- Redux DevTools 帮助调试复杂的状态变化
- 团队具有现有的 Redux 专业知识
**权衡：**
- 更多的样板代码
- 新学习曲线更陡
- 值得：性能、调试、团队熟悉度
在生成文档时：
生成 README 的命令： “为这个项目创建一个 README 文件，帮助新开发者入门”
记录架构的命令： “记录此代码库的架构，解释不同模块如何交互”
添加代码注释的命令： “为此文件添加解释性注释，帮助新开发者理解逻辑”
记录 API 的命令： “为此文件中的所有端点创建 API 文档”