# TECH_DOC

> 为代码仓库生成/更新 TECH_DOC.md（技术文档/技术说明/TECH-DOC）。只要用户提到“TECH_DOC/TECH-DOC/技术文档/技术说明/项目结构梳理/核心流程说明/CLI 参数说明/接口文档/CI/CD 接入”，就优先使用本技能，按固定章节产出可复制的命令与示例，且不杜撰仓库不存在内容。

- Skill: `allenchinese/tech-doc` (Agent Skill)
- Install (CLI): `npx skillmds@latest add allenchinese/tech-doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/allenchinese/tech-doc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: AllenChinese (https://skillmd.com/u/allenchinese)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/allenchinese/tech-doc

---


# TECH_DOC 生成 Skill（全局）

目标：让读者在不翻代码的情况下理解“项目做什么、如何使用、核心流程、外部依赖（接口/DB/文件）、CI/CD 接入方式与边界”。

## 适用范围

- 适用于为任意仓库生成/更新 `TECH_DOC.md`（尤其是 Node.js/TypeScript CLI 工具仓库）。
- 默认输出中文；如用户指定则输出英文。

## 输入要求（尽量少问）

优先从仓库自洽推导；仅在信息缺失且无法推断时再询问用户：
- 仓库根目录（默认当前工作区）
- 目标读者（默认研发）
- 是否需要覆盖：服务端接口 / 数据库 / CI/CD / 宿主项目接入（默认都覆盖；缺失则标注“未实现/可选/由调用方提供”）

## 工作流程（必须遵循）

1) 扫描仓库结构（最多 3 层）
- 找到入口文件（CLI entry）、核心模块、配置文件与文档（如 README）。

2) 读取关键信息源
- `package.json`：name/version/bin/scripts/dependencies/engines
- `README.md`（如存在）
- `tsconfig.json`（如存在）
- `src/`（或等价目录）的入口文件与核心模块（按调用链路补齐）

3) 抽取“可执行信息”
- CLI：命令名、参数列表、必填项、默认值、示例命令
- 配置：环境变量、配置文件字段与优先级
- 核心流程：从入口到核心逻辑的 3-7 步链路
- 外部依赖：HTTP 接口、数据库、文件输入输出、Git 信息等

4) 生成/更新 `TECH_DOC.md`
- 章节编号使用中文序号（“一、二、三 …”），风格统一。
- 代码片段只截取关键段落，避免整文件大段粘贴。
- 示例必须可复制（命令/JSON/YAML/HTTP），敏感信息用占位符。

## 输出结构（TECH_DOC.md 固定模板）

严格按下述结构输出；若某块在仓库不存在，保留标题并写明“未实现/可选/由调用方提供”。

### 文档标题与简介

- 一级标题：`# 📦 <project-name> <一句话定位>`
- 简介两行内：明确“做什么/不做什么”，强调边界（例如：不负责构建，只负责读取产物并上传）

### 一、项目结构

- tree（最多 3 层）
- 关键文件职责说明（入口/核心流程/HTTP/DB/文件/类型等）

### 二、package.json

- 罗列关键字段并解释用途（bin、scripts、依赖、Node 版本等）

### 三、核心代码

按“从入口到核心逻辑”的顺序组织（建议 3-6 小节）：
- 入口：参数解析与校验、help、错误退出策略
- 类型：核心入参/出参/配置结构
- 主流程：版本获取、产物定位、md5/size、Git 信息、上传、落库（如有）
- 模块边界：HTTP/DB/file 等职责清晰
- 失败场景：参数缺失、文件不存在、上传失败、DB 失败（是否允许跳过/重试）

### 四、使用方式（宿主项目接入）

- 安装（npm/yarn/pnpm）
- scripts 推荐写法
- 产物准备方式（若工具不负责构建，要明确由谁构建、产物放哪）
- 最小可用命令（按平台/环境给 2-4 条）

### 五、CI/CD 示例

- 给出仓库当前最贴近的 CI 示例（如 GitHub Actions）
- 说明 secrets/env 注入方式，严禁泄露真实值
- 说明构建与上传顺序，必要时给出重试/失败处理建议

### 六、目录结构参考

- 给出宿主项目推荐目录结构（bundle 与 assets）
- 明确默认路径与可覆盖方式（如 `--bundle-path`）

### 七、服务端接口

- 上传接口：method/path/content-type
- 参数与含义（platform/env/version/md5/fileSize 等）
- 响应体示例与关键字段说明

### 收尾说明

- 用 1-2 句总结工具边界与版本定位（例如：已移除构建逻辑，只负责读取 bundle 并上传）

## 写作规范（强约束）

- 不杜撅：仓库未出现的脚本/接口/文件，不写成“已存在”，只能写“建议/可选”
- 不泄露：token、密码、私钥一律用占位符；不要在日志/示例里输出敏感信息
- 可维护：章节结构固定；关键名词可搜索（参数名/环境变量/接口路径必须原样出现）
- 可复制：示例可直接复制粘贴运行（占位符清晰）

## 可直接复用的提示词（Copy-Paste）

---
你是技术文档专家。请在仓库根目录生成或更新 TECH_DOC.md，要求：
1) 先扫描项目结构并读取关键文件（package.json、README、tsconfig、src 入口与核心模块）。
2) 严格按以下章节输出：简介、 一、项目结构 二、package.json 三、核心代码 四、使用方式 五、CI/CD 示例 六、目录结构参考 七、服务端接口、收尾说明。
3) 不杜撰仓库不存在的内容；缺失处写“未实现/可选/由调用方提供”。
4) 所有示例（命令/JSON/YAML/HTTP）可复制，敏感信息用占位符。
---