dido-platform-docs-writer

仓库运维文档

用于运行项目的手册：在本地启动、部署到生产环境，以及出问题时了解故障原因。读者是维护人员，而非评估人员：他们不需要知道项目可扩展，只需要准确的命令和变量。

黄金法则：只记录仓库文件能够证实的内容。 每一项运维信息（端口、变量、命令、域名、部署步骤）都必须能追溯到某个具体文件。无法追溯时，结果就是 NON DEDUCIBILE，这是合理且常见的结果。一份包含十个已核实章节、三个标记为 NON DEDUCIBILE 的 README，远胜于一份一半内容靠猜测补全的 README：只有这样，文档在六个月后才能依然可靠。

一项事实，只记录一处。 文档应说明文件本身无法说明的内容：操作流程（如何启动、更新和修复，以及所需的命令和 URL）、决策及其原因、每项服务的作用，以及缺失的内容。其余信息应指向来源：端口、版本、变量、镜像和卷都应留在各自的文件中，文档只需指出是哪一个文件。重复列出文件中已有定义的表格、清单或图表，本质上都是副本：写下时可能是对的，但第一次变更后就会过时。因此，即使现有文档中的副本仍然正确，也应将其删除，并改为指向来源。

何时不要使用

• 面向产品或最终用户的文档：为使用应用程序的人编写，而非为运行应用程序的人编写。这是不同的工作，也需要不同的语气。
• 可从代码生成的 API 参考文档（OpenAPI、docstring、typedoc）：这类文档应通过生成得到，而非手动编写；手动编写意味着创建第二份可能与原文档不一致的事实来源。
• 你无法读取的仓库：只有 URL、截图或用户口头描述。没有文件就无从推断——请如实说明并停止，不要凭空还原。
• 架构或技术栈选择：这项技能描述已有内容，而不提出应该采用什么。如果阅读时发现问题（已提交到版本控制的 secret、没有 healthcheck 的服务、指向未在任何地方定义的主机的脚本），请在文档末尾的“待核实事项”下记录，然后继续：运维手册不应变成代码审查。
• 小幅修改（修正一条命令、更新一个引用）：直接修改即可，无需使用这里的完整工作流。

目标

• 让未参与编写项目的人也能独立启动项目，无需向任何人询问。
• 始终区分本地开发和生产环境，并说明两种环境中各项事务由谁管理。
• 记录在仓库中实际发现的配置（编排器、代理、部署引擎、变量管理器），并使用其真实名称。如果仓库使用 Coolify 和 Traefik，就写 Coolify 和 Traefik；如果使用 Kubernetes、Fly.io 或 systemd unit，就写这些。没有任何预设技术栈。
• 避免运维受阻：说明难以满足的前置条件、服务间依赖关系和常见错误。

写作约束，而非语气要求

• 每句话都要帮助读者启动、更新或修复项目。只有一两个服务时，README 控制在约 1,000 词，且不超过 1,500 词；服务更多时，README 只提供总体概览，具体内容放在各服务文档中。
• 只有在读者需要打开某个文件时才引用它，写出文件名，不标注行号：每次修改后行号都会变化。逐行检查由 gate 执行，不由文档负责。
• 使用短句和常规标点：每段最多使用一个长破折号；术语与解释之间使用冒号。
• 不使用无法衡量的形容词（“强大”“可扩展”“现代”）：如果不是数值或命令，就不是操作文档。
• 每条命令都放在可复制且完整的 bash 代码块中，不要在正文中写零散片段。
• 环境之间的比较一律放在表格中，不写在段落里。
• 指令使用祈使句和第二人称（“启动”“验证”），不要使用条件句。

第 1 步：Discovery（清单也是交付内容的一部分）

读完文件后再写任何内容。不要在回复中粘贴读到的原始内容，但务必说明你读了什么：清单是文档的证据基础，必须与文档一并交付。没有记录的 discovery，无法与未进行的 discovery 区分。

要查找的内容	位置	可确定的信息
技术栈和运行时	package.json、pyproject.toml、go.mod、composer.json、lockfile	语言、版本、已定义的脚本
编排	Dockerfile*、compose*.y*ml、override、chart、manifest	服务、内部端口、卷、依赖项、启动命令
配置	.env.example、config/、settings.*	变量、必填项、默认值
自动化	Makefile、justfile、scripts/、.github/workflows/	实际命令、CI 中运行的内容、仍需手动执行的内容
网络与对外暴露	代理 label、nginx.conf、反向代理配置、ingress	TLS 在何处终止、流量如何路由、使用哪些主机名
历史记录	当前 README、CHANGELOG、docs/	过去的情况；需要验证，绝不能直接采纳

完成 discovery 时，用以下这一行作为回复的开头：

Discovery: N file letti. Stack {…}, servizi {…}, deploy {…}. Non trovato: {elenco}.

如果某个领域没有对应文件（没有 CI、代理或备份），这本身就是信息，不是需要填补的空缺：将它列入 non trovato，并据此写入“不可推断”章节。如果无法读取仓库（你只有 URL、截图或用户的描述），就停止并说明原因：没有文件，就无从推断。

结果与门禁

每项操作性陈述都有以下三种结果之一：

结果	适用情况	在文档中的写法
已记录	有文件可证明	普通文本
部分记录	文件展示了机制，但没有给出值（变量存在，但没有值）	文本 + 注释 需确认：{内容}
无法推断	没有文件可证明	明确标注，绝不写看似合理的内容

必须使用以下格式的标注，照抄：

无法推断 — {主题}。 仓库中没有任何文件说明{内容}。 已检查的文件：{列表}。要补全此部分，需要：{能提供信息的人或事物}。

交付前门禁。 这不是建议，而是交付条件：

1. 写出的每条命令都必须出现在仓库文件中，或由其中出现的内容组成。
2. 提到的每个变量都必须存在于 .env.example、compose 文件或代码中。
3. 文档中写出的每个端口、主机和路径都必须来自文件，而非记忆。
4. 每个有要求但文件不支持的部分，都必须包含“无法推断”标注。
5. 每条故障排除内容都必须涉及仓库中确实存在的组件。
6. 任何表格、列表或图表都不得重复文件中已有定义的内容（端口、版本、变量、镜像、卷）：应改为引用文件名。

结尾加上这一行：门禁：已复核 X 项陈述，其中 Y 项降级为“无法推断”。 如果 Y = 0，而该仓库不是你编写的，请重新检查那些最容易想当然的陈述，例如端口、版本、部署和备份。如果这些内容都有文件依据，那么 Y = 0 也是有效结果。

常见自我合理化及必须采取的应对方式

你正在想什么	应该怎么做
“Postgres 的端口是 5432”	引用公开该端口的文件。如果没有：标注为“无法推断”。
“列出变量和端口的表格更易于阅读”	这只是 .env.example 和 compose 文件的副本：第一次更改时就会过时。请引用这些文件。
“这样的项目应该会有备份”	标注为“无法推断”。没有备份本身就是一项发现。
“我先写个通用的 TLS 部分，之后再让他们修改”	不会有人修改：看似合理的内容比空白更糟。
“用户明确要求了 pipeline 部分”	写出该部分，但内容应为“无法推断”标注。
“旧 README 是这么写的”	如果它是某个文件的副本，就删掉并改为引用该文件。其余内容只有在当前代码能够证实时才有效，否则必须指出。
“这个框架的标准命令是……”	标准并不等同于这个仓库的实际情况。
“没有那部分的话，README 看起来不完整”	不完整的是仓库，README 必须如实说明。

如果用户要求删除“无法推断”标注：拒绝，并说明这些标注界定了文档的有效范围。可以将它们集中放在最后的“待补充”部分，但不能删除。

文档结构

reference/struttura-documenti.md 中的结构是参考目录，不是需要填满的索引。只有符合以下两种情况之一的章节才会写入文档：

• 发现阶段找到了相关内容 → 使用实际值撰写，并注明文件；
• 用户明确要求，但发现阶段没有找到相关内容 → 该章节只包含 NON DEDUCIBILE 模块。

无人要求、文件也不支持的章节不写入：其缺失情况记录在“待补充”中，而不是用泛泛的文字填充。

示例说明二者的区别。如果 .env.example 中包含 BACKUP_DIR=，但仓库里没有使用它的脚本或 cron，那么 Backup 章节应写成这样：

NON DEDUCIBILE — Backup。 .env.example 中存在变量 BACKUP_DIR，但没有任何文件使用它：没有脚本、compose 中没有服务，也没有工作流。因此无法推断备份是否执行、何时执行、保留策略是什么，也无法推断由谁恢复备份。已检查的文件：.env.example、compose.yaml、scripts/、.github/workflows/。需要服务器管理员确认。

确定章节范围后，加载 reference/struttura-documenti.md，并使用 assets/ 中的模板——每次只在即将撰写相应文档时加载一个模板，不要提前加载。

故障排查

故障排查条目应根据清单推导，而不是来自固定列表。 只有导致问题的组件出现在已读取的文件中，该条目才会写入文档：仓库中没有签发证书的组件，就不写 TLS 章节；没有文件提及域名，就不写 DNS 章节；没有 .env.example，就不写因变量缺失导致的崩溃循环。按组件整理的参考目录位于 reference/troubleshooting.md，按检测到的技术分类（反向代理、容器编排器、CI/CD、数据库、服务器访问）：把它当作参考目录来查找条目，绝不能当作需要填满的索引。文档中最多包含五条，选出最可能适用于该仓库的条目。

如果仓库使用了参考目录未涵盖的技术，仍需根据其文件推导并撰写相关条目，并在回复的“参考目录更新建议”下列出，而不是默默添加到参考目录中。这些条目不应写入文档：文档属于项目，而非该 skill。

交付

如果环境允许写入文件，请直接写入文件（README.md、docs/NOME-SERVIZIO.md、.env.example 中的注释），回复中只保留摘要。只有无法写入磁盘或用户提出要求时，才在聊天中粘贴完整 Markdown：两者可能运行在不同主机上，不要假定你当前使用的是哪一种。

回复按以下顺序包含：

1. Discovery 行和 Gate 行，各占一行：只列名称和编号，不写说明。
2. 已创建或修改的文件列表，注明路径。
3. 待补充：汇总 NON DEDUCIBILE 模块，并注明谁可以补充各项信息。
4. 待核查项：仓库中发现、维护者应检查的异常（已纳入版本控制的 secret、没有 healthcheck 的服务、指向未定义主机的脚本）。文档中最多列出五项最严重的问题，即那些会导致无法启动或暴露数据与 secret 的问题；其他问题只列在回复中。
5. 参考目录更新建议，如有。

以上列表中的每一项各占一行。

重写现有文档不等于删除它。 如果替换 README，请在回复中列出删除的章节及其原因（文件副本、与代码矛盾、内容过时）。如果某项陈述与事实矛盾，请写明原文说了什么，以及哪个文件予以反证：相信该陈述的人必须知情。文件无法证明、但也未予以反驳的非操作性内容（联系方式、协议、历史记录、团队备注）应原样保留：这些内容不应通过推断得出，因此也不应被删除。