| name | docs-output |
| description | 基础设施技能——维护项目 docs/ 目录的模块化组织和进度追踪。由编排器在 Plan 末尾和 Deliver 阶段强制调用，禁止跳过。模块文档按业务维度分目录存放详细内容，进度记录按日期/会话hash存放摘要。支持多人协作和跨会话任务追溯，文件头部标识 Git 账号。 务必在以下场景使用本 skill：创建文档、文档目录管理、docs 目录、产出物管理、输出文档、document output、docs management、模块文档、文档分类、多人协作文档、跨会话文档、进度记录、任务摘要、progress、会话记录、开发日志。 |
文档产出管理
本 Skill 解决两个核心问题：
- 文档产出缺乏统一组织：模块文档散落、分类混乱
- 缺少任务进度记录：模型处理需求/修复 Bug 后没有简要摘要，回溯困难
本 Skill 管理 docs/ 目录的两类内容：模块详细文档 + 进度摘要记录。
数据模型
graph TD
TASK["模型执行任务<br/>需求分析 · Bug修复 · 技术方案"]
MODULES["docs/{module}/<br/>模块文档<br/>详细功能描述"]
PROGRESS["docs/progress/{date}/{hash}.md<br/>进度摘要<br/>会话级记录"]
TASK -->|"详细产出"| MODULES
TASK -->|"摘要记录"| PROGRESS
style TASK fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
style MODULES fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
style PROGRESS fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
原则
- 编排器强制调用：本 skill 是基础设施，由 orchestrator 在 Plan 末尾和 Deliver 阶段强制调用，禁止跳过。
- 模块化组织（强制）：模块文档必须按业务维度分目录（如
docs/auth/login.md）。禁止扁平输出（如 docs/login.md）。
- 一会话一文件：进度记录按日期/会话hash独立存放，多人不冲突。
- 只管结构不管内容格式：文档内容格式由调用方决定。
- Git 账号标识：进度记录头部包含开发者 Git 账号。
禁止事项
- 禁止将文档直接放在
docs/ 根目录下（如 docs/login.md）。必须放在业务模块子目录下（如 docs/auth/login.md）。
- 禁止跳过本 skill。如果任务产生了文档，必须通过本 skill 组织存放。
- 禁止省略进度记录。每次任务完成必须写入
docs/progress/{date}/{username}_{hash}.md。
- 禁止手动生成时间戳。所有时间（日期、时分秒）必须由
docs_manager.py 脚本产生，禁止 LLM 自行计算或拼接时间字符串（常见错误：UTC时间手动+8小时产生 25:xx 等非法时间）。
目录结构
docs/
├── auth/ # 业务模块 — 详细文档
│ ├── login.md
│ └── register.md
├── user/
│ ├── profile.md
│ └── settings.md
├── progress/ # 进度记录
│ ├── 2024-01-15/
│ │ ├── zhangsan_a3f8c1.md # 用户名_会话hash
│ │ └── lisi_b7d2e4.md
│ ├── 2024-01-16/
│ │ └── zhangsan_c9e5f0.md
│ └── archive/ # 归档（>30天）
│ └── 2024-01/
│ └── ...
模块文档规则
- 一级目录 = 业务模块（如
auth、user、dashboard）
- 二级文件 = 页面/功能点（如
login.md、register.md）
- 模块名和文件名使用 kebab-case
- 中文项目可用中文命名
进度记录规则
- 路径：
docs/progress/{YYYY-MM-DD}/{username}_{会话hash}.md
- username：取
git config user.name（空格替换为 -，全小写）
- 会话hash：6位随机十六进制（如
a3f8c1），保证唯一
- 同会话持续追加：同一个 Agent 会话窗口内，所有进度记录追加到同一个文件中，不新建文件。只有切换到新会话窗口时才生成新的会话hash。
- 同一天可有多个会话文件（不同人/不同任务）
- 必须使用脚本：进度记录的创建和追加必须通过
python scripts/docs_manager.py progress 命令执行，禁止 LLM 直接生成/写入进度 Markdown 文件。脚本保证时间戳使用系统本地时间（datetime.now()），避免时区计算错误。
完整命名规则见 → references/naming-rules.md
进度记录模板
每个文件包含一个或多个记录条目。同会话中每完成一个任务，追加一个 --- 分隔的条目。仅包含有内容的段落，空段落不输出：
# 会话进度：{username}_{hash}
> huyongle <568055454@qq.com> · 2026-04-09 10:38:13 起
---
## [10:38:13] 用户认证模块需求分析 · 需求开发
完成登录/注册流程的领域模型设计
- `docs/auth/login.md` — 新增登录流程文档
> **决策**: 采用 JWT + Refresh Token 双令牌方案
---
## [10:52:40] 修复 Token 刷新竞态 · Bug修复
并发 refresh 导致旧 token 覆盖新 token，用互斥锁解决
> **遗留**: 补充 refresh token 过期降级方案
---
## [11:05:22] 代码审查 · 其他
Review PR #42，无变更
规则：类型合并到标题（[时间] 主题 · 类型）；变更文件直接列在摘要后；决策/遗留用 > 引用块；无内容的段落不输出。
核心能力
1. create — 创建模块文档
在指定模块目录下创建新文档。
- 自动创建模块目录（如不存在）
- 生成空白文档（仅包含一级标题）
2. update — 创建或更新模块文档（含内容）
创建或覆盖指定模块文档，内容由参数提供。Deliver 阶段强制使用此命令。
- 不存在则创建，已存在则覆盖更新
--content 参数传入完整 Markdown 正文（包含功能描述、接口定义、技术决策等）
3. progress — 记录进度
创建或追加会话进度记录。
- 首次调用：新建
{username}_{hash}.md，写入头部（Git 信息）+ 首条记录
- 传入
--session-id：追加条目到已有文件，每条记录带 [HH:mm:ss] 秒级时间
- 返回
session_id，后续调用复用
4. list — 列出文档
按模块和进度分别列出 docs/ 下所有内容。
5. validate — 校验目录
检查文档目录的基本健康状态。
6. archive — 归档旧进度
将超过 30 天的进度记录移入 progress/archive/YYYY-MM/。
多人协作
- 模块粒度隔离：不同开发者负责不同模块目录，天然避免文件冲突
- 进度无冲突：每个会话独立文件（日期+hash），多人同时工作不会冲突
- 分支工作流：每人在独立 Git 分支上工作，通过 PR 合入
- Git 账号追溯：进度记录头部包含
git user.name 和 git user.email，可追溯到具体开发者
Python 脚本
python scripts/docs_manager.py create --root <project_root> --module <模块名> --name <文档名> [--title <一级标题>]
python scripts/docs_manager.py update --root <project_root> --module <模块名> --name <文档名> --content <内容> [--title <标题>]
python scripts/docs_manager.py progress --root <project_root> --topic <主题> --type <类型> --summary <摘要> [--session-id <会话ID>] [--files <变更文件JSON>] [--decisions <决策>] [--todos <遗留>]
python scripts/docs_manager.py list --root <project_root>
python scripts/docs_manager.py validate --root <project_root>
python scripts/docs_manager.py archive --root <project_root> [--older-than <天数>]
输出均为 JSON 格式，便于模型解析。
