mirror of https://github.com/GeWuYou/GFramework.git synced 2026-05-06 16:16:44 +08:00

gewuyou 66395739dc docs(governance): 收口公开文档治理口径

- 更新 AGENTS.md、DOCUMENTATION_STANDARDS.md 与 gframework-doc-refresh 规则，禁止在公开文档中暴露 inventory、覆盖基线与恢复点

- 修复 Core、Game、Ecs.Arch 与 abstractions 栏目中的 XML 覆盖表述，改为面向使用者的源码阅读入口

- 补充 contributor 页面 frontmatter，并统一 landing page、验证基线等内部术语为读者导向表达

- 更新 documentation-full-coverage-governance tracking 与 trace，记录 -batch-boot 75 基线、验证结果和下一步

2026-04-24 08:31:23 +08:00

4.1 KiB

Raw Permalink Blame History

GFramework 文档编写规范

本文件只保留跨模块稳定生效的写作与校验规则，不再维护容易失真的固定页面清单。

模块到源码、测试、README、docs/zh-CN 栏目以及 ai-libs/ 参考入口的映射，统一以 .agents/skills/_shared/module-map.json 为准。

证据顺序

统一按以下顺序判断文档应写什么、删什么、保留什么：

源码、公开 XML docs、*.csproj
对应测试和 snapshot
模块 README.md
当前 docs/zh-CN 页面
ai-libs/ 下已验证的消费者项目
归档文档，仅在前述证据无法解释当前行为时回看

不要把旧文档互相抄写当成“更新”。

模块驱动规则

先按源码模块归一化输入，再决定落到 landing page、专题页、API reference、教程还是仅做校验。
如果用户给的是栏目名而不是源码模块名，先映射回模块；若仍有歧义，只给归一化建议，不直接生成文档。
文档栏目是派生输出，不是主输入源。

`ai-libs/` 使用边界

ai-libs/ 只用于补消费者视角证据：

验证真实接入目录结构
查最小 wiring、扩展点装配方式
给 adoption path 提供端到端例子

不要用 ai-libs/ 覆盖以下事实：

公共 API 契约
当前版本支持范围
Source Generator 诊断与生成语义

如果 ai-libs/ 与当前源码或测试冲突，以当前仓库实现为准，并在文档里写明迁移或兼容边界。

公开文档边界

README.md 与 docs/** 面向框架使用者，不面向治理执行者。
不要把 inventory、覆盖基线、恢复点、批处理阈值、review 线程、待补审计波次等内部治理信息写进公开页面。
XML、README、测试与 ai-libs/ 证据可以驱动文档决策，但公开页面只能输出读者真正需要的内容：
- 模块边界
- 最小接入路径
- 推荐阅读顺序
- 源码 / XML / API 的入口提示
如果确实需要保留治理基线、盘点结果或后续治理计划，把它写到 ai-plan/** 或其他 contributor-only 记录里。
当页面需要引用 XML 文档时，写“应优先查看哪些类型、命名空间或契约，以及为什么”，不要写覆盖数量、盘点日期或“已覆盖 / 未覆盖”状态。

Markdown 规则

泛型与 HTML 转义

代码块外出现泛型或 XML 标签时必须转义：

List<T>
Result<TValue, TError>
<summary>
<param>

Frontmatter

每个文档都必须包含合法 frontmatter：

---
title: 文档标题
description: 1-2 句话描述当前页面解决什么问题
---

代码块

始终标注语言，如 csharp、bash、json
示例只保留当前实现可追溯的最小路径
必要时写中文注释解释接入原因或边界，不要堆砌与代码同步无关的注释

链接

只链接到当前仓库真实存在的页面
站内链接优先使用 /zh-CN/... 形式
如果文档站不允许跳出 docs/ 根目录，就不要把仓库 README 写成站内链接

输出优先级

统一按以下顺序决定产出：

先修模块 README、landing page 与 adoption path
再修失真的专题页
再补 API reference
最后才补教程

用户页检查点

用户读完页面后，应知道怎么采用、该看哪几个入口，而不是知道当前治理批次做到哪一轮。
如果一段内容删掉日期、数量、基线、治理术语后就失去价值，它大概率不该出现在公开文档里。
表格优先表达“何时看什么、解决什么问题”，不要表达“当前盘点覆盖到哪里”。

验证清单

frontmatter 正确
代码块语言标记齐全
泛型和 XML 标签已转义
站内链接存在
示例与当前实现一致
ai-libs/ 只作为消费者接入参考，没有覆盖源码契约

验证工具

统一复用 gframework-doc-refresh/scripts/ 下的校验脚本：

validate-frontmatter.sh
validate-links.sh
validate-code-blocks.sh
validate-all.sh

需要站点级验证时，执行：

cd docs && bun run build

4.1 KiB Raw Permalink Blame History Unescape Escape