Dsh Doc

---
name: dsh-doc
description: "创建、重构或审查文档、README、文档树与网站内容；按读者任务组织层次，核实操作事实、双语同步、导航和生成来源。"
---

# dsh-doc

本 Skill 仅用于当前项目。用户授权、项目 AGENTS.md 和实际宿主能力优先。

## 定位与结构

读根及目标目录规则、目标页面、代码/测试、导航和双语 counterpart。明确读者起点、想完成的动作、可观察结果、常见失败/恢复及下一层详情。

一页承担一个主要任务：quick start、操作指南、教程、架构、包/子系统 reference、生成 reference、代理指令、决定记录或临时草稿。先根据用途区分教程和查阅文档，不按目录猜；混合过重时沿已有 owner 拆分。包合同靠近包，跨包知识归现有 docs。先讲用户能做什么，再解释实现；精确 API/字段目录链接代码或生成物，避免手抄另一份权威。

标题和稳定锚点使用可搜索术语，前提先于操作；长页给必要导航和分节导语。metadata、kind、模板、行宽及章节格式遵循本项目现行规范，不擅自引入 DSH 的 YAML kind、固定 Summary/Dev Note 或物理行数规则。

## 核实事实

- 从 manifest、入口和实际接口判断包是工具、插件、库或 bundle；不能从目录名推导安装方式。先读真实安装 owner，不从邻近包抄命令。
- 配置、默认值、错误、平台行为和操作步骤逐项绑定当前代码及证据。已获授权的安全操作照文档原样试跑；生产、外部写入、凭据或不可逆条件缺失时标记未验证与验证路径，不为了文档可信度越权操作。
- 核实失败就修说明，不为保留文字改测试。禁止从记忆/类比补出无证据命令；未验证项不能写成已经支持。旧文档以当前真实基线校正，远端版本有必要时只读核对，不强制抓取错误的 master 分支。
- 修改 owner 后再生成派生目录、catalog 和网站页面。文档搬迁同时处理导航与全部活跃入站链接；冻结历史保持原貌，引用它时标记历史。
- `README.md` 与 `README.zh-CN.md` 的重大产品、安装、证据、兼容、安全或许可变化同改；其他成对文档按实际约定维护语义、结构、术语、代码与目标链接。

## 文档审计

按授权范围逐页检查主要读者与任务，再看归属、先后层次、重复规则、手工清单、未来计划混入现状、私有讨论引用和可执行性。保留必需的失败、权限、兼容与恢复合同；字数只用来定位难检索的段落，不能作删减目标。

用常用路径长度、一次查询需要扫描的不相关内容、最大节、标题数等判断是否应拆分。若项目有字数预算，先移到适当 owner/精简重复，再有理由地调整预算；不是压缩或删掉必要承诺。行为简化与文案精简分开决定。

## 网站与交付

已有网站只作为仓库 Markdown 的投影：修改 canonical 内容、当前路由/allowlist 和入站链接，运行既有生成/preview；不手改 generated/cache/dist。新增网站或部署不是普通文档请求隐含的任务，构建成功不等于已发布。

运行适用的链接/格式、双语、生成新鲜度、命令及项目强制检查；新增机械 gate 要有有效输入和真实拒绝的负对照。人工复核准确性、可读性和 newcomer 能否沿少量链接到达答案。报告改动、执行过的操作、材料来源与具体未验证项，不把 Markdown 可解析当作内容正确。

来源、适配边界和许可证见 [provenance.md](provenance.md)。