@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/documentation-writer/assets/templates/STACK.md

@@ -0,0 +1,56 @@
+# Technology Stack
+
+## Core Sections (Required)
+
+### 1) Runtime Summary
+
+| Area | Value | Evidence |
+|------|-------|----------|
+| Primary language | [VALUE] | [FILE_PATH] |
+| Runtime + version | [VALUE] | [FILE_PATH] |
+| Package manager | [VALUE] | [FILE_PATH] |
+| Module/build system | [VALUE] | [FILE_PATH] |
+
+### 2) Production Frameworks and Dependencies
+
+List only high-impact production dependencies (frameworks, data, transport, auth).
+
+| Dependency | Version | Role in system | Evidence |
+|------------|---------|----------------|----------|
+| [NAME] | [VERSION] | [ROLE] | [FILE_PATH] |
+
+### 3) Development Toolchain
+
+| Tool | Purpose | Evidence |
+|------|---------|----------|
+| [TOOL] | [LINT/FORMAT/TEST/BUILD] | [FILE_PATH] |
+
+### 4) Key Commands
+
+```bash
+[install command]
+[build command]
+[test command]
+[lint command]
+```
+
+### 5) Environment and Config
+
+- Config sources: [LIST FILES]
+- Required env vars: [VAR_1], [VAR_2], [TODO]
+- Deployment/runtime constraints: [SHORT NOTE]
+
+### 6) Evidence
+
+- [path/to/manifest]
+- [path/to/runtime-config]
+- [path/to/build-or-ci-config]
+
+## Extended Sections (Optional)
+
+Add only when needed for complex repos:
+
+- Full dependency taxonomy by category
+- Detailed compiler/runtime flags
+- Environment matrix (dev/stage/prod)
+- Process manager and container runtime details

package/skills/documentation-writer/assets/templates/STRUCTURE.md

@@ -0,0 +1,44 @@
+# Codebase Structure
+
+## Core Sections (Required)
+
+### 1) Top-Level Map
+
+List only meaningful top-level directories and files.
+
+| Path | Purpose | Evidence |
+|------|---------|----------|
+| [path/] | [purpose] | [source] |
+
+### 2) Entry Points
+
+- Main runtime entry: [FILE]
+- Secondary entry points (worker/cli/jobs): [FILES or NONE]
+- How entry is selected (script/config): [NOTE]
+
+### 3) Module Boundaries
+
+| Boundary | What belongs here | What must not be here |
+|----------|-------------------|------------------------|
+| [module/layer] | [responsibility] | [forbidden logic] |
+
+### 4) Naming and Organization Rules
+
+- File naming pattern: [kebab/camel/Pascal + examples]
+- Directory organization pattern: [feature/layer/domain]
+- Import aliasing or path conventions: [RULE]
+
+### 5) Evidence
+
+- [path/to/root-tree-source]
+- [path/to/entry-config]
+- [path/to/key-module]
+
+## Extended Sections (Optional)
+
+Add only when repository complexity requires it:
+
+- Subdirectory deep maps by feature/layer
+- Middleware/boot order details
+- Generated-vs-source layout boundaries
+- Monorepo workspace-level structure maps

package/skills/documentation-writer/assets/templates/TESTING.md

@@ -0,0 +1,57 @@
+# Testing Patterns
+
+## Core Sections (Required)
+
+### 1) Test Stack and Commands
+
+- Primary test framework: [NAME + VERSION]
+- Assertion/mocking tools: [TOOLS]
+- Commands:
+
+```bash
+[run all tests]
+[run unit tests]
+[run integration/e2e tests]
+[run coverage]
+```
+
+### 2) Test Layout
+
+- Test file placement pattern: [co-located/tests folder/etc]
+- Naming convention: [pattern]
+- Setup files and where they run: [paths]
+
+### 3) Test Scope Matrix
+
+| Scope | Covered? | Typical target | Notes |
+|-------|----------|----------------|-------|
+| Unit | [yes/no] | [modules/services] | [notes] |
+| Integration | [yes/no] | [API/data boundaries] | [notes] |
+| E2E | [yes/no] | [user flows] | [notes] |
+
+### 4) Mocking and Isolation Strategy
+
+- Main mocking approach: [module/class/network]
+- Isolation guarantees: [what is reset and when]
+- Common failure mode in tests: [short note]
+
+### 5) Coverage and Quality Signals
+
+- Coverage tool + threshold: [value or TODO]
+- Current reported coverage: [value or TODO]
+- Known gaps/flaky areas: [list]
+
+### 6) Evidence
+
+- [path/to/test-config]
+- [path/to/representative-test-file]
+- [path/to/ci-or-coverage-config]
+
+## Extended Sections (Optional)
+
+Add only when needed:
+
+- Framework-specific suite patterns
+- Detailed mock recipes per dependency type
+- Historical flaky test catalog
+- Test performance bottlenecks and optimization ideas

package/skills/documentation-writer/references/api-docs.md

@@ -0,0 +1,185 @@
+# API 文档
+
+API 文档是参考文档，读者是要调用它的开发者。他们带着具体问题来查：这个接口要什么参数、返回什么、出错时怎么办。所以要准、要全、结构要统一，不需要讲故事。
+
+API 文档分两种，先分清：
+
+- **HTTP 接口**（REST、RPC 风格、GraphQL）：从路由、校验 schema、中间件、错误处理里提取。
+- **库 / SDK 参考**：从公开导出的函数、类、类型签名和注释里提取。
+
+## 目录
+
+- [HTTP 接口：找全端点](#http-接口找全端点)
+- [HTTP 接口：每个端点要查清的事](#http-接口每个端点要查清的事)
+- [输出格式：Markdown 还是 OpenAPI](#输出格式markdown-还是-openapi)
+- [Markdown 接口文档结构](#markdown-接口文档结构)
+- [OpenAPI 规范](#openapi-规范)
+- [库 / SDK 参考](#库--sdk-参考)
+- [完整性核对](#完整性核对)
+
+## HTTP 接口：找全端点
+
+漏掉端点是接口文档最常见的问题。先找全，再逐个写。
+
+1. **找路由定义**。按框架找注册方式，同时找路由前缀（子路由挂载在哪个路径下），前缀拼错会让整份文档的路径都错：
+
+   | 框架 | 路由写法 | 前缀 / 分组 |
+   |---|---|---|
+   | Express / Koa Router | `app.get(...)`、`router.post(...)` | `app.use('/api', router)`、`new Router({ prefix })` |
+   | Fastify | `fastify.get(...)`、`fastify.route({ method, url })` | `register(plugin, { prefix })` |
+   | Hono | `app.get(...)` | `app.route('/api', sub)`、`basePath()` |
+   | Elysia | `.get('/path', handler, { body, query, params })` | `new Elysia({ prefix })`、`.group('/x', ...)` |
+   | NestJS | `@Get(':id')`、`@Post()` | `@Controller('users')`、全局 `setGlobalPrefix` |
+   | FastAPI | `@app.get(...)`、`@router.post(...)` | `APIRouter(prefix=...)`、`include_router(..., prefix=...)` |
+   | Flask | `@app.route('/x', methods=[...])` | Blueprint 的 `url_prefix` |
+   | Django / DRF | `urls.py` 的 `path()`、`ViewSet` | `include()`、`router.register()` |
+   | Spring | `@GetMapping`、`@PostMapping` | 类上的 `@RequestMapping` |
+   | Gin / Echo / Chi | `r.GET(...)`、`e.POST(...)`、`r.Get(...)` | `r.Group("/v1")`、`r.Route(...)` |
+   | Go net/http 1.22+ | `mux.HandleFunc("GET /users/{id}", ...)` | 外层 mux 的 `Handle` 前缀 |
+   | Rails | `config/routes.rb` 的 `resources`、`get` | `namespace`、`scope` |
+   | Laravel | `routes/api.php` 的 `Route::get` | `Route::prefix()->group()` |
+   | ASP.NET | `[HttpGet]`、minimal API 的 `app.MapGet` | `[Route("api/[controller]")]`、`MapGroup` |
+
+   框架能列出路由的，优先用它的输出核对：`bin/rails routes`、`php artisan route:list`、FastAPI 的 `/openapi.json`、Spring Actuator 的 `/actuator/mappings`。
+
+2. **数清楚**。统计路由注册的数量，写文档前记下这个数，写完核对。路由注册经常跨行（`.post(` 换行后才是路径），逐行 `grep` 会漏掉一大截，要用能跨行匹配的方式数。例如链式注册的框架（Express、Hono、Elysia、Fastify）：
+
+   ```bash
+   python3 - <<'EOF'
+   import re, pathlib
+   pat = re.compile(r"\.(get|post|put|patch|delete)\(\s*['\"`]([^'\"`]+)", re.I)
+   routes = sorted((m[1].upper(), m[2], str(p)) for p in pathlib.Path("src").rglob("*.[jt]s")
+                   for m in pat.finditer(p.read_text(encoding="utf-8")))
+   print(len(routes)); [print(*r) for r in routes]
+   EOF
+   ```
+
+   装饰器风格（NestJS、FastAPI、Spring）按装饰器改正则。统计结果和你的端点清单对不上时，找出差异再继续。
+
+3. **分组**。按资源（用户、订单）或按路由文件分组，组内按「列表、详情、创建、更新、删除、其他动作」排序。
+
+## HTTP 接口：每个端点要查清的事
+
+| 要查的 | 去哪里找 |
+|---|---|
+| 方法和完整路径 | 路由定义 + 所有前缀拼起来 |
+| 鉴权方式、需要的角色 / 权限 / scope | 路由上的中间件、guard、装饰器，全局鉴权插件；有没有例外（公开接口） |
+| 路径参数、查询参数 | 路由声明、校验 schema；默认值和取值范围从 schema 或代码里取 |
+| 请求体字段、类型、必填、约束 | 校验库：zod、TypeBox（Elysia 的 `t.Object`）、Joi、yup、class-validator DTO、pydantic 模型、Go struct tag、Bean Validation 注解 |
+| 响应结构 | handler 的返回值、序列化器、统一响应包装函数；数据库 schema 只作参考，以实际返回的字段为准 |
+| 错误 | handler 里的 `throw` / 返回的错误、全局错误处理（Express 错误中间件、Elysia `onError`、FastAPI `exception_handler`、Spring `@ControllerAdvice`）、错误码常量文件 |
+| 分页、排序、过滤 | 分页工具函数、查询参数解析 |
+| 副作用 | 发消息、写审计日志、调外部服务、触发异步任务 |
+| 幂等、并发、限流 | 幂等键、乐观锁、限流中间件 |
+
+**例子里的数据**从测试用例、seed 脚本、fixture、schema 里取形状：ID 是 UUID 还是自增整数还是带前缀的字符串，金额是整数分还是小数字符串，时间是 ISO 字符串还是时间戳。形状要对，值可以是假的。token、密钥一律用占位符（`<your-token>`）。
+
+**代码里缺注释**的端点，不要替它编一个说明。从 handler 逻辑读出它做什么；实在读不出业务意图的，写行为（「按 `status` 过滤并返回最近 50 条」），并标 `[ASK USER]` 问用途。
+
+## 输出格式：Markdown 还是 OpenAPI
+
+- 默认写 **Markdown**，给人读。
+- 用户要 OpenAPI / Swagger，或者仓库已经在用 OpenAPI 工具链（有 `openapi.yaml`、swagger UI、代码生成客户端），写或更新 **OpenAPI**。
+- 框架已经从代码自动生成 OpenAPI（FastAPI、NestJS 的 `@nestjs/swagger`、Elysia 的 swagger 插件、springdoc）时，不要再手写一份平行的规范，两份会不一致。告诉用户生成地址，文档只补自动生成覆盖不到的内容：鉴权流程、错误码含义、调用顺序、示例。需要完善生成结果的，建议在代码注解上改，改源码前先问用户。
+
+## Markdown 接口文档结构
+
+```markdown
+# <服务名> API
+
+## 概览
+- Base URL：各环境地址（从配置里取，不确定的标 [TODO]）
+- 鉴权：怎么拿凭证、放在哪个请求头
+- 响应格式：统一的成功 / 失败信封结构，给一个例子
+- 分页：参数名、默认值、上限
+- 错误：错误响应的结构，完整错误码表在文末
+- 共 N 个端点（与代码核对过的数字）
+
+## 端点一览
+| 方法 | 路径 | 说明 | 权限 |
+
+## <资源名>
+
+### GET /users/{id}  获取单个用户
+
+一句话说明它做什么、什么时候用。
+
+**权限**：`users:read`
+
+**路径参数**
+| 参数 | 类型 | 说明 |
+
+**查询参数**
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+
+**请求体**
+| 字段 | 类型 | 必填 | 约束 | 说明 |
+
+**响应** `200`
+（JSON 示例）
+
+**错误**
+| 状态码 | 错误码 | 什么时候出现 |
+
+**注意**：幂等性、副作用、调用顺序等，没有就不写。
+
+代码位置：`src/routes/users.ts:42`
+
+## 错误码
+| 错误码 | HTTP 状态 | 含义 | 调用方该怎么处理 |
+```
+
+没有请求体的端点不写「请求体」小节，不要留一个写着「无」的空表。每个端点给一个 `curl` 示例还是只在概览里给一个，看文档长度决定：端点少于 15 个可以每个都给，多了只给有代表性的。
+
+## OpenAPI 规范
+
+- 版本：仓库工具链有要求就照做，否则用 `openapi: 3.1.0`。`info.version` 取 manifest 里的版本号。
+- `servers` 从配置里取；本地地址和端口要和代码一致。
+- 字段结构放进 `components/schemas`，用 `$ref` 复用；鉴权放进 `components/securitySchemes`，在操作或全局上声明 `security`。
+- 每个操作都要有：`operationId`（稳定、唯一，客户端代码生成要用）、`tags`、`summary`、参数、`requestBody`（有的话）、成功响应和主要错误响应。
+- 枚举值、`minimum` / `maximum`、`maxLength`、`format`（`uuid`、`date-time`、`email`）从校验 schema 里照搬，不要猜。
+- 写完校验：本机有 `npx` 且能联网时跑 `npx @redocly/cli lint <文件>`；不行至少确认 YAML 能被解析。校验结果写进交付说明。
+
+一个最小片段示意格式：
+
+```yaml
+paths:
+  /users/{id}:
+    get:
+      operationId: getUser
+      tags: [users]
+      summary: 获取单个用户
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
+      responses:
+        '200':
+          description: 用户详情
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/User' }
+        '404':
+          description: 用户不存在
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+```
+
+## 库 / SDK 参考
+
+1. **找公开面**：`package.json` 的 `exports` / `main` / `types` 和入口 barrel 文件，Python 的 `__init__.py` 与 `__all__`，Go 的大写导出标识符，Rust `lib.rs` 里的 `pub`，Java 的公开 API 包。没导出的不写，写了读者会去用。
+2. **每个导出项写**：签名（从代码复制，不要手打）、参数（类型、是否可选、默认值）、返回值、会抛出的错误、一个最小示例；有 `@deprecated` 或版本说明的照实写。
+3. **组织**：按使用顺序（初始化、主要操作、辅助工具、类型）组织，比按字母排序好用。开头给一段「最小可用示例」，让读者 30 秒内跑通。
+4. **仓库已经在用 TypeDoc、Sphinx、rustdoc、godoc 这类生成器**的，优先建议补源码注释再生成；手写文档只补生成器给不了的内容（概念说明、完整示例、迁移指南）。
+
+## 完整性核对
+
+交付前逐项确认：
+
+- [ ] 文档里的端点数等于代码里统计出的端点数；有意不写的（内部接口、调试接口）在文档或交付说明里列出来
+- [ ] 每个路径都拼上了完整前缀，和一个真实请求能对上
+- [ ] 每个端点的权限要求都查过中间件，不是猜的
+- [ ] 请求字段的必填、约束与校验 schema 一致
+- [ ] 错误码表里的每个码在代码里都能找到出处
+- [ ] 示例 JSON 的字段名和响应代码一致
+- [ ] 代码注释缺失、只能推断用途的端点已标 `[INFERRED]` 或 `[ASK USER]`

package/skills/documentation-writer/references/architecture.md

@@ -0,0 +1,134 @@
+# 架构文档
+
+目标是一份可以直接交给新工程师的文档：覆盖整个系统，难的部分讲得够深，而且每个结论都能追到本地文件，所以读者敢信。它属于 Diátaxis 里的「解释」加一部分「参考」：讲清系统怎么搭起来、为什么这样搭，同时给出可查的清单（技术栈、命令、目录、运行面）。
+
+## 目录
+
+- [范围：整个仓库还是一个子系统](#范围整个仓库还是一个子系统)
+- [工作方法](#工作方法)
+- [文档结构](#文档结构)
+- [图怎么画](#图怎么画)
+- [让文档可信的几条习惯](#让文档可信的几条习惯)
+- [范围控制](#范围控制)
+
+## 范围：整个仓库还是一个子系统
+
+- 用户说「这个仓库」「整个系统」：写全仓架构，按下文完整结构。
+- 用户指定了一个服务或模块（monorepo 里的一个 app）：以它为主体，结构照用，但「系统上下文」要画出它和仓库里其他部分、外部服务的关系；和它无关的部分不写。
+- 仓库特别大（几十个服务）：先写全局地图（上下文图 + 容器图 + 每个服务一行），深挖只挑两三个最关键的子系统，其余在文末列为「未覆盖」，不要每个都浅浅写一段。
+
+## 工作方法
+
+1. **锚定快照**：remote（去掉凭据）、分支、HEAD 提交、版本号、许可证，写进文档开头的「快照信息」表。
+2. **先识别，不假设**：读 manifest、任务脚本、CI 配置、仓库里给 agent 或贡献者看的文档（`AGENTS.md`、`CLAUDE.md`、`CONTRIBUTING`、`docs/`）。技术栈和命令以这些为准。
+3. **先铺广度，再挖深度**：先建立全仓地图（技术栈、入口、目录、运行面），再挑两三个最难的子系统深挖。
+4. **边写边核对**：引用哪个文件哪一行，就打开读那一行。没有依据的结论比空着更糟。
+
+## 文档结构
+
+默认写成**一个** Markdown 文件，按下面顺序。按项目实际调整标题：CLI 工具没有「前端」，就把那一格换成对这个项目重要的东西，但保留整体形状和核对纪律。
+
+### 1. 快照信息
+
+| 项 | 值 |
+|---|---|
+| 仓库 | remote URL（已去凭据） |
+| 分支 / 提交 | `main` / `a1b2c3d`（日期） |
+| 版本 | manifest 里的版本号 |
+| 许可证 | `LICENSE` 里的类型 |
+
+### 2. 这是什么
+
+一段话：系统做什么、给谁用、在更大的体系里处于什么位置。引用 README 或入口代码。
+
+### 3. 技术栈
+
+表格，列「层 | 技术 | 版本 | 依据（文件:行）」。区分生产依赖和开发工具。
+
+### 4. 入口
+
+后端服务、前端应用、CLI、后台任务、定时任务，各自从哪个文件启动、怎么启动。
+
+### 5. 命令与验证清单
+
+列「命令 | 用途 | 依据」，覆盖：安装、构建、启动、测试（包括怎么只跑一个测试）、lint、格式化，有的话再加类型检查、端到端测试、契约测试、数据库迁移、种子数据。每条命令都要能在任务脚本、manifest 或 CI 配置里找到，找不到的标 `[UNVERIFIED]`。
+
+再写 CI：哪些 workflow、什么时候触发、跑哪些命令。CI 是否是**合并前必须通过的检查**（分支保护、required status check）通常看不出来，这是在代码托管平台上手动配置的；问用户，或者标 `[UNVERIFIED]`。
+
+### 6. 目录结构
+
+每个主要目录一行说明用途。monorepo 按 workspace 分别列。路径别名（`tsconfig.json` 的 `paths`）先映射成真实路径再写。
+
+### 7. 部署与运行面
+
+所有「运行时」版本被钉住的地方：容器基础镜像（`Dockerfile` 的 `FROM`）、`docker-compose` 里的服务镜像和版本、CI runner 镜像和 `setup-*` 版本、`engines` / `.nvmrc` / `.tool-versions`、serverless 运行时、数据库 / 缓存 / 消息队列的镜像 tag。每项带出处。构建用的版本和运行用的版本不一致时，在这里指出来。
+
+### 8. 数据与存储
+
+有哪些数据库、各自存什么、谁读谁写、迁移怎么管理、有没有多租户隔离、缓存和消息队列的用途。
+
+### 9. 架构蓝图
+
+- **系统上下文图**（C4 第一层）：系统和用户、外部系统的关系。
+- **容器图**（C4 第二层）：系统内部可以独立部署或运行的单元（服务、前端、数据库、队列）以及它们之间的通信方式。
+- **一个典型请求的完整链路**：从入口到存储再返回，挑最有代表性的一个（登录、下单、核心业务操作）。
+- **分层与依赖规则**：什么可以依赖什么，谁来保证（lint 规则、目录约定、代码评审、构建工具）。没有强制手段的，如实写「靠约定」。
+- **横切关注点**：表格，列「关注点 | 实现位置 | 依据」，覆盖鉴权、配置、日志、指标 / 链路追踪、密钥、错误处理、特性开关、国际化，有哪些写哪些。
+- **推断出的架构决策**：从代码和文档里还原关键决策，每条写「决策、可能的原因、带来的约束」，标 `[INFERRED]`，有明确文档依据的除外。
+- **治理机制**：CI 门禁、代码生成校验、CODEOWNERS、评审规则、兼容性规则（前后端分开发布、存储双向兼容、protobuf 只增不改之类）。这些是新人最容易踩的规矩。
+
+### 10. 子系统深挖
+
+挑两三个最复杂或最关键的子系统：新人最难看懂的那部分，例如调度引擎、插件加载流程、状态机、权限计算、计费。每个写：
+
+- 内部结构和关键类型
+- 生命周期或状态流转
+- 数据怎么流动
+- 一张小图（时序图或状态图）
+- 带行号的引用
+
+这部分是架构文档和目录清单的区别所在，值得多花时间。
+
+### 11. 新人指南
+
+- 加一个功能要动哪些地方，按顺序列出（路由、校验、服务、数据库迁移、前端、测试、文档）。
+- 常见的坑：测试默认 watch 模式、构建很慢、生成的代码要提交、pre-commit hook 会改文件、本地要先起哪些服务。每条带出处。
+
+### 12. 依赖健康（可选）
+
+已经停止维护或到了生命周期末期的运行时、框架、基础镜像、库。按实际情况标 `[INFERRED]` 或 `[UNVERIFIED]`，不要凭印象断言某个版本已经 EOL。
+
+### 13. 可信度评估
+
+表格，列「主题 | 可信度 | 说明」，可信度取「高 / 推断 / 未验证」。读者据此知道哪些可以直接信，哪些要自己再查。
+
+### 14. 依据文件
+
+文档依赖的关键本地文件，每个一行说明它证明了什么。
+
+## 图怎么画
+
+按 SKILL.md 的「出图」一节先探测 archify。架构文档里常用的图和对应的 archify 类型：
+
+| 图 | archify 类型 | Mermaid 兜底 |
+|---|---|---|
+| 系统上下文图 | `architecture` | `flowchart LR` |
+| 容器图 / 部署拓扑 | `architecture` | `flowchart` 加 `subgraph` 表示边界 |
+| 典型请求链路 | `sequence` | `sequenceDiagram` |
+| 子系统状态机 | `lifecycle` | `stateDiagram-v2` |
+| 数据管道、事件流 | `dataflow` | `flowchart LR` |
+| 业务流程、发布流程 | `workflow` | `flowchart TD` |
+
+一份全仓架构文档一般三到五张图：上下文图、容器图、一条请求链路，再加深挖子系统里各一张。图里出现的每个组件，正文里都要有对应的文字说明。
+
+## 让文档可信的几条习惯
+
+- **每个非显而易见的结论都引用本地路径**，钉住具体东西时带行号（`pkg/server/server.go#L39-L41`）。路径相对仓库根，方便点击。
+- **如实标记不确定**：推理出来的标 `[INFERRED]`，转述未核实的标 `[UNVERIFIED]`。
+- **矛盾要裁定**：manifest 写的版本和代码里的不一致，读代码定下真实答案，写一句「已核对：……」说明依据。不要把矛盾原样丢给读者。
+- **写出兼容性和发布节奏的规矩**，这是新人最容易违反的。
+- **用精确数字**：「73 个 service 包」「89 个 workflow 文件」（来自目录统计），不写「很多服务」。
+
+## 范围控制
+
+文档只写这份 checkout 里看得到的东西。很容易越写越远：相关产品、README 里的宣传、兄弟仓库。除非在磁盘上看得到，否则不写；确实需要提的，明确标出来源不是本地代码。读者要的是**这个代码库**被如实记录下来。

package/skills/documentation-writer/references/codebase-map.md

@@ -0,0 +1,113 @@
+# 代码库说明（docs/codebase/ 成套文档）
+
+在 `docs/codebase/` 下产出八份文档，覆盖在这个项目里高效工作需要知道的一切：技术栈、目录、架构、约定、功能、外部集成、测试、风险。它们是随查随用的参考，读者是日常改代码的工程师和 AI agent，所以每份都要短、结构固定、结论有出处。只写能从文件或命令输出里核实的东西，不推测。
+
+和架构文档的区别：架构文档是一篇从头读到尾的解释；这里是八张按主题拆开的参考卡片。
+
+## 目录
+
+- [交付要求](#交付要求)
+- [流程](#流程)
+- [聚焦模式](#聚焦模式)
+- [容易出错的地方](#容易出错的地方)
+- [反例](#反例)
+
+## 交付要求
+
+结束前以下各条都要成立：
+
+1. `docs/codebase/` 下正好有这八个文件：`STACK.md`、`STRUCTURE.md`、`ARCHITECTURE.md`、`FEATURES.md`、`CONVENTIONS.md`、`INTEGRATIONS.md`、`TESTING.md`、`CONCERNS.md`。文件名保持英文（方便工具和 agent 查找），标题和正文用文档语言。
+2. 每条结论都能追到源文件、配置或命令输出。
+3. 查不到的标 `[TODO]`；取决于团队意图的标 `[ASK USER]`。
+4. 每份文档末尾有「依据」小节，列出具体文件路径。
+5. 模板里的占位符（`[VALUE]`、`[FILE_PATH]`、`[path/to/...]` 这类）全部替换掉，不能留在成品里。
+6. 交付回复里编号列出所有 `[ASK USER]` 问题，以及「文档意图与代码现实」的分歧。
+
+范围是 monorepo 的一个子包时，文件放在该子包的 `docs/codebase/` 下，或者按用户指定的位置。
+
+## 流程
+
+照这个清单推进：
+
+```
+- [ ] 1. 扫描，读意图文档
+- [ ] 2. 按主题调查
+- [ ] 3. 按模板填写八份文档
+- [ ] 4. 校验、修补、汇报
+```
+
+### 1. 扫描，读意图文档
+
+1. 在目标目录跑扫描：
+
+   ```bash
+   python3 "$SKILL_DIR/scripts/scan.py" --output docs/codebase/.codebase-scan.txt
+   ```
+
+   扫描结果包括目录树、manifest、入口、lint 配置、环境变量模板、TODO / FIXME、近期提交、近 90 天高频改动文件、monorepo 信号、CI、容器、安全配置、性能测试标记、按语言的代码量。交付前删掉这个中间文件，或者提醒用户不要提交它。
+2. 找 `PRD`、`TRD`、`README`、`ROADMAP`、`SPEC`、`DESIGN` 之类的文件读一遍。
+3. 读源码之前，先用几句话总结这个项目**声称**要做什么。第 4 步要拿它和代码现实对比。
+
+### 2. 按主题调查
+
+用扫描结果回答每份文档的问题，八份文档各自的问题清单在 [inquiry-checkpoints.md](inquiry-checkpoints.md)。扫描答不了的，读源文件。技术栈不明确时读 [stack-detection.md](stack-detection.md)。
+
+### 3. 按模板填写
+
+把 `$SKILL_DIR/assets/templates/` 里的模板复制到 `docs/codebase/`，按这个顺序填（后面的会用到前面的结论）：
+
+1. `STACK.md`：语言、运行时、框架、依赖、命令
+2. `STRUCTURE.md`：目录、入口、模块边界
+3. `ARCHITECTURE.md`：分层、模式、数据流
+4. `FEATURES.md`：功能清单与关键功能的执行路径
+5. `CONVENTIONS.md`：命名、格式、错误处理、导入
+6. `INTEGRATIONS.md`：外部 API、数据库、鉴权、监控
+7. `TESTING.md`：测试框架、文件组织、mock 策略
+8. `CONCERNS.md`：技术债、缺陷、安全风险、性能瓶颈
+
+模板标题是英文，按文档语言翻译。默认只填每个模板的「Core Sections (Required)」；「Extended Sections (Optional)」只在仓库复杂度确实需要时加。
+
+`ARCHITECTURE.md` 里的数据流、`FEATURES.md` 里的关键功能路径适合配图，按 SKILL.md 的「出图」一节处理，图放在 `docs/codebase/diagrams/`。
+
+### 4. 校验、修补、汇报
+
+必须做完这个循环再交付：
+
+1. 对照 inquiry-checkpoints.md 逐份检查。
+2. 每条非显而易见的结论至少有一处依据。
+3. 跑 `python3 "$SKILL_DIR/scripts/check_doc.py" docs/codebase/*.md --repo-root <仓库根>`，修掉不存在的路径和残留的占位符。
+4. 有缺失的必填章节或没有依据的结论：修文档，再校验，直到八份都通过。
+
+通过标准：没有无依据的结论；必填章节不空；不知道的用 `[TODO]` 而不是猜；团队意图的空白标 `[ASK USER]`。
+
+然后给用户一份汇报：八份文档各一句话概要、编号的 `[ASK USER]` 问题、第 1 步总结的意图与代码现实之间的分歧。
+
+## 聚焦模式
+
+用户指定了重点（「只要架构」「测试和风险」）时：
+
+1. 第 1 步照样完整做。
+2. 先把重点文档写完整。
+3. 其余文档保留必填章节结构，没调查的地方标 `[TODO]`。
+4. 第 4 步的校验循环仍然覆盖全部八份。
+
+## 容易出错的地方
+
+- **monorepo**：根 `package.json` 可能没有源码。看 `workspaces`、`packages/`、`apps/`。每个 workspace 的依赖和约定可能各不相同，分开写。
+- **README 过时**：README 常描述理想中的架构。当事实用之前先和目录结构对一下。
+- **TypeScript 路径别名**：`tsconfig.json` 的 `paths` 让 `@/foo` 这种导入不对应真实目录，先映射再写结构。
+- **生成产物**：不要从 `dist/`、`build/`、`generated/`、`.next/`、`out/`、`__pycache__/` 里总结约定。
+- **`.env.example` 暴露了必需配置**：密钥不会提交，但模板文件会列出需要哪些环境变量。
+- **`devDependencies` 不是生产栈**：只有 `dependencies`（或等价物，如 `[tool.poetry.dependencies]`）在生产环境运行。lint、格式化、测试框架单独写成开发工具。
+- **测试里的 TODO 不是生产债**：`test/`、`tests/`、`__tests__/`、`spec/` 里的 TODO 是覆盖缺口，在 `CONCERNS.md` 里和生产代码的技术债分开列。
+- **高频改动文件就是脆弱区**：近期提交里出现最多的文件，改动率高，往往藏着复杂度。一定写进 `CONCERNS.md`。
+
+## 反例
+
+| 不要这样 | 应该这样 |
+|---|---|
+| 「采用 Clean Architecture，分 Domain / Data 层」（实际没有这些目录） | 只写目录结构真实体现的东西 |
+| 「这是一个 Next.js 项目」（没看 `package.json`） | 先查 `dependencies`，写实际有的 |
+| 从 `dbUrl` 这个变量名猜数据库类型 | 在 manifest 里找 `pg`、`mysql2`、`mongoose`、`prisma` 等 |
+| 把 `dist/` 里的命名方式写成项目约定 | 只看源文件 |
+| 「功能包括用户管理、权限管理等」 | 在 `FEATURES.md` 里逐项列出，每项带入口和核心代码位置 |

package/skills/documentation-writer/references/inquiry-checkpoints.md

@@ -0,0 +1,78 @@
+# 调查问题清单
+
+写代码库说明（[codebase-map.md](codebase-map.md)）第 2 步用。每份文档先在扫描结果里找答案，找不到再读源文件。
+
+---
+
+## 1. STACK.md：技术栈
+
+- 主要语言和确切版本？（看 `.nvmrc`、`go.mod`、`pyproject.toml`、Dockerfile 的 `FROM`）
+- 用的什么包管理器？（`npm`、`yarn`、`pnpm`、`bun`、`go mod`、`pip`、`uv`）
+- 核心运行时框架有哪些？（Web 服务器、ORM、依赖注入容器）
+- `dependencies`（生产）和 `devDependencies`（开发工具）里分别有什么？
+- 有没有 Docker 镜像，基础镜像是什么？
+- `package.json` / `Makefile` / `pyproject.toml` 里的关键脚本有哪些？
+
+## 2. STRUCTURE.md：目录结构
+
+- 源码放在哪？（通常是 `src/`、`lib/`，Go 项目常在根目录）
+- 入口是哪些？（`package.json` 的 `main`、`scripts.start`、`cmd/main.go`、`app.py`）
+- 每个顶层目录的用途是什么？
+- 有没有不直观的目录（`eng/`、`platform/`、`infra/`）？
+- 有哪些隐藏的配置目录（`.github/`、`.vscode/`、`.husky/`）？
+- 目录命名遵循什么规律？（camelCase、kebab-case，按领域分还是按层分）
+
+## 3. ARCHITECTURE.md：架构模式
+
+- 代码按层组织（controller → service → repository）还是按功能组织？
+- 主要数据流是什么？从入口到数据存储完整追踪一个请求或命令。
+- 有没有单例、依赖注入、必须按顺序初始化的东西？
+- 有没有后台 worker、队列、事件驱动的组件？
+- 反复出现的设计模式有哪些？（Factory、Repository、Decorator、Strategy）
+
+## 4. FEATURES.md：功能
+
+- 用户或调用方能用到哪些功能？从路由、页面、CLI 命令、菜单配置、权限定义里列全。
+- 每个功能的入口在哪（路由、页面组件、命令），核心逻辑在哪，读写哪些表或外部服务？
+- 哪三到五个功能最重要（最常用、改动最频繁、最复杂）？把它们在代码里的执行路径走一遍。
+- 有哪些特性开关、租户级配置、套餐限制会改变功能行为？
+- 有没有写了但没接上入口的功能，或者入口在但实现是空的？
+
+## 5. CONVENTIONS.md：编码约定
+
+- 文件命名规则？（至少看 10 个文件：camelCase、kebab-case、PascalCase）
+- 函数和变量的命名规则？
+- 私有方法和字段有没有前缀（`_methodName`、`#field`）？
+- 配了哪些 linter 和 formatter？（看 `.eslintrc`、`.prettierrc`、`biome.json`、`golangci.yml`）
+- TypeScript 严格程度怎么设的？（`strict`、`noImplicitAny` 等）
+- 每一层怎么处理错误？（抛异常还是返回结构化错误）
+- 用什么日志库，日志格式是什么？
+- 导入怎么组织？（barrel 导出、路径别名、分组规则）
+
+## 6. INTEGRATIONS.md：外部集成
+
+- 调用了哪些外部 API？（搜 `axios.`、`fetch(`、`http.Get(`、常量里的 base URL）
+- 凭据怎么存、怎么取？（`.env`、密钥管理服务、环境变量）
+- 连了哪些数据库？（在 manifest 里找 `pg`、`mongoose`、`prisma`、`typeorm`、`drizzle-orm`、`sqlalchemy`）
+- 应用和外部服务之间有没有 API 网关、服务网格或代理？
+- 用了哪些监控或可观测性工具？（APM、Prometheus、日志管道）
+- 有没有消息队列或事件总线？（Kafka、RabbitMQ、SQS、Pub/Sub、Redis Streams）
+
+## 7. TESTING.md：测试
+
+- 配的什么测试运行器？（看 `package.json` 的 `scripts.test`、`pytest.ini`、`go test`、`bun test`）
+- 测试文件放在哪？（和源码放一起、`tests/`、`__tests__/`）
+- 用什么断言库？（Jest expect、Chai、pytest assert）
+- 外部依赖怎么 mock？（`jest.mock`、依赖注入、fixture）
+- 有没有连真实服务的集成测试，还是只有 mock 的单元测试？
+- 有没有强制的覆盖率门槛？（看 `jest.config.js`、`.nycrc`、`pyproject.toml`、`bunfig.toml`）
+
+## 8. CONCERNS.md：风险与问题
+
+- 生产代码里有多少 TODO / FIXME / HACK？（看扫描结果）
+- 近 90 天改动最频繁的是哪些文件？（看扫描结果）
+- 有没有超过 500 行、混了多种职责的文件？
+- 有没有可以并行却串行调用的服务？
+- 有没有该放进配置却写死的值（URL、ID、魔法数字）？
+- 有哪些安全风险？（缺输入校验、把原始错误信息返回给客户端、缺鉴权检查）
+- 有没有扩展不了的性能写法？（N+1 查询、多实例部署下的进程内缓存）