Back to Details

docs-sync

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

docs-sync

文档同步（docs-sync）

Synchronizes documentation with implementation after 
/speckit.implement
completes.
在
/speckit.implement
执行完成后，将文档与实现代码同步。

Purpose

用途

This skill automatically updates documentation to reflect the implemented features. It:
  • Updates README.md: Adds/updates usage section with implementation details
  • Updates CHANGELOG.md: Adds entries for new features and changes
  • Updates API docs: Synchronizes API documentation with contracts
  • Preserves user content: Content outside speckit markers is never modified
该Skill会自动更新文档以反映已实现的功能，具体包括：
  • 更新README.md：添加/更新使用部分，补充实现细节
  • 更新CHANGELOG.md：为新功能和变更添加条目
  • 更新API文档：使API文档与契约保持同步
  • 保留用户内容：speckit标记之外的内容绝不会被修改

Marker System

标记系统

docs-sync uses HTML comment markers to delineate auto-generated sections:
markdown
<!-- speckit:start:section-name -->
Auto-generated content here
<!-- speckit:end:section-name -->
Content outside these markers is preserved exactly as-is.
docs-sync使用HTML注释标记来界定自动生成的区域：
markdown
<!-- speckit:start:section-name -->
Auto-generated content here
<!-- speckit:end:section-name -->
这些标记之外的内容将完全按原样保留。

Output

输出结果

The skill outputs a DocsSyncResult showing:
  • Files created, updated, or unchanged
  • Sections modified within each file
  • Diff summary (lines added/removed/changed)
  • Any errors encountered
该Skill会输出一个DocsSyncResult，包含以下信息：
  • 已创建、更新或未变更的文件
  • 每个文件中被修改的区域
  • 差异摘要（添加/删除/修改的行数）
  • 遇到的所有错误

Usage

使用方法

This skill runs automatically after 
/speckit.implement
. You can also run it manually:
bash
npx skills run docs-sync
该Skill会在
/speckit.implement
执行完成后自动运行，也可以手动运行：
bash
npx skills run docs-sync

Exit Codes

退出码

CodeStatusMeaning
0SuccessAll updates successful
1PartialSome updates failed
3ErrorRequired files missing
代码状态含义
0成功所有更新操作完成
1部分完成部分更新操作失败
3错误缺少必要文件

Sections Updated

已更新的区域

README.md

README.md

SectionMarkerContent Source
Usage
<!-- speckit:start:usage -->
spec.md user stories
Installation
<!-- speckit:start:installation -->
plan.md dependencies
Features
<!-- speckit:start:features -->
spec.md functional requirements
区域标记内容来源
使用方法
<!-- speckit:start:usage -->
spec.md 用户故事
安装
<!-- speckit:start:installation -->
plan.md 依赖项
功能特性
<!-- speckit:start:features -->
spec.md 功能需求

CHANGELOG.md

CHANGELOG.md

SectionMarkerContent Source
Unreleased
<!-- speckit:start:unreleased -->
tasks.md completed tasks
区域标记内容来源
未发布内容
<!-- speckit:start:unreleased -->
tasks.md 已完成任务

Preservation Rules

内容保留规则

  1. Content before the first marker is always preserved
  2. Content after the last marker is always preserved
  3. Content between different marker pairs is always preserved
  4. Only content within matching marker pairs is updated
  5. If no markers exist, content is appended with new markers
  1. 第一个标记之前的内容始终保留
  2. 最后一个标记之后的内容始终保留
  3. 不同标记对之间的内容始终保留
  4. 仅更新匹配标记对之间的内容
  5. 如果不存在标记，则在内容末尾添加新标记并补充内容

Error Handling

错误处理

  • Missing markers: Creates new markers and adds content
  • Malformed markers: Reports error, skips that section
  • File permissions: Reports error, continues with other files
  • Missing source files: Reports which sources are unavailable
  • 缺少标记：创建新标记并添加内容
  • 标记格式错误：报告错误，跳过该区域
  • 文件权限问题：报告错误，继续处理其他文件
  • 缺少源文件：报告哪些源文件不可用