mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-13 06:04:30 +08:00
8209d7a29f
- 修复公开 README 与 docs 页面中的反问式标题、维护者口吻和裸文件名链接标签 - 补充 AGENTS.md 与 gframework-doc-refresh 的 reader-facing 文档输出约束 - 更新 documentation-full-coverage-governance 的恢复点与验证记录
219 lines
6.8 KiB
Markdown
219 lines
6.8 KiB
Markdown
---
|
|
name: gframework-doc-refresh
|
|
description: "Refresh or reassess GFramework documentation for a source module such as Core, Game, Godot, Cqrs, Ecs.Arch, or their generator/abstraction packages. Use this when the user asks to update module docs, re-evaluate landing pages, fix outdated topic pages, refresh API reference coverage, verify adoption paths against source/tests/README, or compare current docs with ai-libs consumer wiring. Recommended command: /gframework-doc-refresh <module>."
|
|
---
|
|
|
|
# Purpose
|
|
|
|
Use this skill to refresh GFramework documentation from source-first evidence.
|
|
|
|
The public entry is module-driven, not doc-type-driven:
|
|
|
|
- Input: a source module or a resolvable docs section alias
|
|
- Output: the minimal documentation update set needed for that module
|
|
- Evidence: code, tests, README, current docs, then `ai-libs/`
|
|
|
|
Do not start by deciding “this is an API doc task” or “this is a tutorial task”.
|
|
Decide that only after the module scan.
|
|
|
|
# Triggers
|
|
|
|
Use this skill when the user asks things like:
|
|
|
|
- `refresh docs for Core`
|
|
- `update Game module docs`
|
|
- `根据 Godot 模块源码刷新文档`
|
|
- `重新评估 Cqrs 模块文档并更新`
|
|
- `核对 Godot.SourceGenerators 的文档状态`
|
|
- `看看 source-generators 栏目哪些页面已经失真`
|
|
|
|
Recommended command form:
|
|
|
|
```bash
|
|
/gframework-doc-refresh <module>
|
|
```
|
|
|
|
# Supported Modules
|
|
|
|
Canonical module names:
|
|
|
|
- `Core`
|
|
- `Core.Abstractions`
|
|
- `Core.SourceGenerators`
|
|
- `Core.SourceGenerators.Abstractions`
|
|
- `Game`
|
|
- `Game.Abstractions`
|
|
- `Game.SourceGenerators`
|
|
- `Godot`
|
|
- `Godot.SourceGenerators`
|
|
- `Godot.SourceGenerators.Abstractions`
|
|
- `Cqrs`
|
|
- `Cqrs.Abstractions`
|
|
- `Cqrs.SourceGenerators`
|
|
- `Ecs.Arch`
|
|
- `Ecs.Arch.Abstractions`
|
|
- `SourceGenerators.Common`
|
|
|
|
The canonical mapping lives in `.agents/skills/_shared/module-map.json`.
|
|
|
|
If the user supplies a docs section name:
|
|
|
|
- resolve it back to a source module first
|
|
- if it maps to multiple modules, stop at normalization guidance and do not draft docs yet
|
|
|
|
# Workflow
|
|
|
|
## 1. Normalize the input
|
|
|
|
Run:
|
|
|
|
```bash
|
|
python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py <module>
|
|
```
|
|
|
|
The script normalizes aliases, reports ambiguity, and prints the module's evidence surface.
|
|
|
|
If the result is ambiguous:
|
|
|
|
- return the candidate modules
|
|
- ask the user to pick the intended source module
|
|
- do not continue into document generation
|
|
|
|
## 2. Scan the evidence surface
|
|
|
|
For the resolved module, inspect:
|
|
|
|
- source directories
|
|
- `*.csproj`
|
|
- relevant test projects
|
|
- sibling `README.md`
|
|
- mapped `docs/zh-CN` landing pages and topic pages
|
|
- optional `ai-libs/` consumer evidence when needed
|
|
|
|
Always confirm the actual files in the repository.
|
|
Do not assume the mapping is enough on its own.
|
|
|
|
## 3. Decide whether `ai-libs/` is needed
|
|
|
|
Use `ai-libs/` when:
|
|
|
|
- adoption path is unclear from source and README alone
|
|
- extension points need a real consumer wiring example
|
|
- current docs have concepts but lack an end-to-end integration path
|
|
|
|
Do not rely on `ai-libs/` for:
|
|
|
|
- public API contract definitions
|
|
- generator diagnostics or semantic guarantees
|
|
- claims about what the current version officially supports
|
|
|
|
If `ai-libs/` conflicts with current source or tests, keep source/tests as the contract and document the migration boundary.
|
|
|
|
## 4. Judge the documentation state
|
|
|
|
Classify the module into one or more of these states:
|
|
|
|
- missing landing page
|
|
- stale landing page
|
|
- stale topic page
|
|
- missing or stale API reference coverage
|
|
- stale tutorial/example
|
|
- validation-only
|
|
|
|
Base this on evidence, not on the previous docs shape.
|
|
|
|
## 5. Choose the output set
|
|
|
|
Always prioritize:
|
|
|
|
1. README / landing page / adoption path
|
|
2. topic pages
|
|
3. API reference
|
|
4. tutorials
|
|
|
|
If the module only needs validation or relinking, do not generate extra pages.
|
|
|
|
## 6. Draft or update docs
|
|
|
|
Load only the template that matches the output you selected:
|
|
|
|
- `templates/module-landing.md`
|
|
- `templates/topic-refresh.md`
|
|
- `templates/api-reference.md`
|
|
- `templates/tutorial.md`
|
|
|
|
Keep examples minimal, current, and traceable to source or tests.
|
|
|
|
## 7. Validate
|
|
|
|
Run the internal validators as needed:
|
|
|
|
```bash
|
|
bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh <file-or-directory>
|
|
```
|
|
|
|
For site-level confirmation after doc edits:
|
|
|
|
```bash
|
|
cd docs && bun run build
|
|
```
|
|
|
|
# Evidence Order
|
|
|
|
Use this exact priority:
|
|
|
|
1. source code, XML docs, `*.csproj`
|
|
2. tests and snapshots
|
|
3. module `README.md`
|
|
4. current `docs/zh-CN` pages
|
|
5. verified `ai-libs/` consumers
|
|
6. archived docs only as fallback context
|
|
|
|
# Output Rules
|
|
|
|
- Prefer correcting the adoption path over expanding page count.
|
|
- Do not copy wording from outdated docs just to keep page volume.
|
|
- Public docs must stay reader-facing. Do not write inventory, coverage baseline, recovery-point, batch-metric, review
|
|
backlog, or audit-wave wording into `README.md` or `docs/**`.
|
|
- Use neutral, destination-first section names and link labels. Do not expose raw filenames or paths such as
|
|
`game/index.md`, `README.md`, or `../core/cqrs.md` as visible reader-facing labels when a semantic label is
|
|
available.
|
|
- Do not use rhetorical or conversational headings in public docs, such as “你真正会用到的公开入口”、
|
|
“先理解包关系” or “想看……转到……”. Prefer direct labels such as “公开入口”、
|
|
“模块与包关系” and “相关主题”.
|
|
- Keep public docs out of internal product-decision tone. Do not publish repository-governance wording such as
|
|
“当前阶段的结论”、“不建议立即启动” or audience-maintainer tradeoff discussions unless the page itself is a public
|
|
adoption guide and the wording has been rewritten as reader-facing suitability guidance.
|
|
- If XML or audit evidence is relevant, translate it into reader guidance such as “which types to inspect first” or
|
|
“which entry points define the contract”, instead of exposing counts, dates, or governance status.
|
|
- Escape generics outside code blocks.
|
|
- Keep internal links real and current.
|
|
- Mark code blocks with explicit languages.
|
|
- Use the smallest example that demonstrates the current contract.
|
|
- Consumer examples may align with `ai-libs/`, but must not exceed the current module contract.
|
|
|
|
# Validation
|
|
|
|
Use the shared standards in `.agents/skills/_shared/DOCUMENTATION_STANDARDS.md`.
|
|
|
|
When this skill changes public docs, prefer:
|
|
|
|
1. focused validator on touched pages
|
|
2. `cd docs && bun run build`
|
|
|
|
When this skill changes the skill system itself:
|
|
|
|
1. validate `SKILL.md` frontmatter exists
|
|
2. run the module scan script for representative modules
|
|
3. confirm obsolete `vitepress-*` public entries are gone
|
|
|
|
# References
|
|
|
|
Read these only when needed:
|
|
|
|
- `.agents/skills/_shared/DOCUMENTATION_STANDARDS.md`
|
|
- `.agents/skills/_shared/module-map.json`
|
|
- `references/module-selection.md`
|
|
- `references/evidence-and-ai-libs.md`
|
|
- `references/output-strategy.md`
|