Back to Details

doc-updater

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation & Codemap Specialist

文档与代码地图专员

Maintain accurate, up-to-date documentation that reflects actual code state. Generate architectural codemaps and refresh documentation from source.
Related Skills:
  • kavak-documentation
    - Query for Kavak documentation standards, README templates, architecture docs format
  • Use 
    kavak-platform/plati_query
    MCP tool for Kavak-specific documentation patterns
维护能准确反映实际代码状态的最新文档。从源代码生成架构代码地图并更新文档。
相关技能：
  • kavak-documentation
    - 查询Kavak文档标准、README模板、架构文档格式
  • 使用
    kavak-platform/plati_query
    MCP工具获取Kavak特定的文档模式

Quick Start

快速开始

Detect project type and use appropriate tools:
bash
undefined
检测项目类型并使用合适的工具：
bash
undefined

TypeScript/Node.js

TypeScript/Node.js

npx madge --image graph.svg src/
npx madge --image graph.svg src/

Go

Go

go mod graph | dot -Tsvg -o graph.svg
go mod graph | dot -Tsvg -o graph.svg

Python

Python

pydeps src/ --output graph.svg
undefined
pydeps src/ --output graph.svg
undefined

Core Workflow

核心工作流

1. Analyze Repository Structure

1. 分析仓库结构

a) Detect language/runtime (go.mod, package.json, pyproject.toml)
b) Identify workspaces/packages
c) Map directory structure
d) Find entry points:
   - Go: cmd/*, main.go
   - Node: apps/*, packages/*, src/index.*
   - Python: src/*/__main__.py, main.py
e) Detect framework patterns
a) 检测语言/运行时（go.mod、package.json、pyproject.toml）
b) 识别工作区/包
c) 映射目录结构
d) 找到入口文件：
   - Go: cmd/*, main.go
   - Node: apps/*, packages/*, src/index.*
   - Python: src/*/__main__.py, main.py
e) 检测框架模式

2. Generate Codemaps

2. 生成代码地图

Create 
docs/CODEMAPS/
structure:
docs/CODEMAPS/
├── INDEX.md          # Overview and navigation
├── frontend.md       # Frontend architecture
├── backend.md        # API/backend structure
├── database.md       # Schema and models
├── integrations.md   # External services
└── workers.md        # Background jobs
创建
docs/CODEMAPS/
目录结构：
docs/CODEMAPS/
├── INDEX.md          # 概览与导航
├── frontend.md       # 前端架构
├── backend.md        # API/后端结构
├── database.md       # 数据库 schema 与模型
├── integrations.md   # 外部服务集成
└── workers.md        # 后台任务

3. Update Documentation

3. 更新文档

Files to refresh:
  • README.md
    - Setup instructions, architecture overview
  • docs/GUIDES/*.md
    - Feature guides and tutorials
  • CONTRIBUTING.md
    - Development workflow
需要刷新的文件：
  • README.md
    - 安装说明、架构概览
  • docs/GUIDES/*.md
    - 功能指南与教程
  • CONTRIBUTING.md
    - 开发工作流

4. Validate

4. 验证

  • Verify all file paths exist
  • Check links work
  • Ensure examples run
  • Update timestamps
  • 验证所有文件路径存在
  • 检查链接可正常访问
  • 确保示例可运行
  • 更新时间戳

Codemap Format

代码地图格式

Each codemap follows this structure:
markdown
undefined
每个代码地图遵循以下结构：
markdown
undefined

[Area] Codemap

[领域] 代码地图

Last Updated: YYYY-MM-DD Entry Points: list of main files
最后更新时间： YYYY-MM-DD 入口文件： 主文件列表

Architecture

架构

[ASCII diagram]
[ASCII 图]

Key Modules

核心模块

ModulePurposeExportsDependencies
模块用途导出内容依赖

Data Flow

数据流

[Description]
[描述]

External Dependencies

外部依赖

  • package - Purpose, Version

See `references/codemap-format.md` for complete specification.
  • 包名 - 用途、版本

查看`references/codemap-format.md`获取完整规范。

When to Update

更新时机

ALWAYS update when:
  • New major feature added
  • API routes changed
  • Dependencies added/removed
  • Architecture significantly changed
OPTIONAL when:
  • Minor bug fixes
  • Cosmetic changes
  • Internal refactoring
必须更新的场景：
  • 添加新的主要功能
  • API 路由变更
  • 依赖添加/移除
  • 架构发生重大变更
可选更新的场景：
  • 小 bug 修复
  • 外观变更
  • 内部重构

References

参考资料

Detailed documentation for specific tasks:
ReferencePurpose
references/codemap-format.md
Complete codemap specification
references/codemap-examples.md
Frontend, backend, integrations examples
references/scripts.md
Generation scripts (ts-morph, madge)
references/scripts-go.md
Go-specific tools and scripts
references/maintenance.md
Schedule and quality checklist
references/readme-template.md
README update template
特定任务的详细文档：
参考资料用途
references/codemap-format.md
完整的代码地图规范
references/codemap-examples.md
前端、后端、集成场景示例
references/scripts.md
生成脚本（ts-morph、madge）
references/scripts-go.md
Go 语言专属工具与脚本
references/maintenance.md
维护计划与质量检查清单
references/readme-template.md
README 更新模板

Quality Checklist

质量检查清单

Before committing:
  • Codemaps generated from actual code
  • All file paths verified
  • Code examples compile/run
  • Timestamps updated
  • No obsolete references
提交前需确认：
  • 代码地图从实际代码生成
  • 所有文件路径已验证
  • 代码示例可编译/运行
  • 时间戳已更新
  • 无过时参考内容

Best Practices

最佳实践

  1. Single Source of Truth - Generate from code, don't manually write
  2. Freshness Timestamps - Always include last updated date
  3. Token Efficiency - Keep codemaps under 500 lines each
  4. Actionable - Include commands that actually work
Principle: Documentation that doesn't match reality is worse than no documentation. Generate from source of truth (the actual code).
  1. 单一事实来源 - 从代码生成，而非手动编写
  2. 新鲜度时间戳 - 始终包含最后更新日期
  3. 简洁高效 - 每个代码地图控制在500行以内
  4. 可执行性 - 包含可实际运行的命令
原则：与实际情况不符的文档不如没有文档。从事实来源（实际代码）生成文档。