updating-internal-docs

更新内部文档

对照代码库的实际状态审查内部文档文件，并对过时、错误或缺失的信息提出修正建议。

何时使用

• 代码库发生重大变化之后（新功能、重构、工具链更新）
• 怀疑文档出现偏差时
• 更新 make 目标、文件夹结构、依赖、技能或工作流之后
• 当 PR 新增或修改 Streamlit 功能时 —— 检查随库附带的技能（lib/streamlit/.agents/skills/）是否需要更新

需要检查的关键文件

优先检查的文件（最可能包含针对具体代码库的说明）：

• **/AGENTS.md - AI Agent 说明
• **/README.md - 包/目录文档
• .claude/skills/*/SKILL.md - 用于 Streamlit 库开发的技能定义
• .claude/agents/*.md - 子 Agent 定义
• wiki/**/*.md - 开发者 wiki
• CONTRIBUTING.md - 贡献者指南
• lib/streamlit/.agents/skills/AGENTS.md - 随库附带技能的编写说明
• lib/streamlit/.agents/skills/*/SKILL.md - 用于 Streamlit 应用开发的随库附带技能（随库一同发布）
• lib/streamlit/.agents/skills/*/references/*.md - 随库附带技能的参考文档

需要跳过的文件（同步副本，另行更新）：

• .github/copilot-instructions.md
• .github/instructions/*.md
• .cursor/rules/*.mdc
• .claude/agents/reviewing-local-changes.md 从 ## Review Checklist 开始的部分（由 scripts/assets/code-review-instructions.md 生成）

如果你编辑了源文件 AGENTS.md 或 scripts/assets/code-review-instructions.md，请运行 uv run python scripts/generate_agent_rules.py，使生成的副本保持同步。

验证清单

• Make 命令存在且可用（make help）
• 文件和文件夹路径存在
• 工具/依赖引用有效
• 工具版本号与配置文件一致（见下文）
• 测试说明正确
• 代码示例与实际模式一致
• 链接可解析（内部和外部）
• 技能/Agent 交叉引用使用当前名称
• .github/workflows/AGENTS.md 反映实际的工作流文件
• CONTRIBUTING.md 的技能/Agent 概览与 .claude/skills/*/ 和 .claude/agents/ 一致
• 随库附带的技能（lib/streamlit/.agents/skills/）反映当前的 Streamlit API 和功能
• 文档中的约定尚未被 lint、format、type-check、Knip 或其他 CI 检查完全强制执行（如果已被强制执行，则视为冗余并省略或删除）

随库附带的技能与功能变更

当 PR 新增或更改 Streamlit 功能（新组件、API 变更、弃用、新能力）时，检查随库附带的技能是否需要更新：

• 编辑随库附带的技能之前，先阅读 lib/streamlit/.agents/skills/AGENTS.md。它决定哪些功能获得重点指导，以及如何更新参考文档、示例、路由和公开 API 摘要。
• lib/streamlit/.agents/skills/developing-with-streamlit/references/ 中的参考文档 —— 更新相关的现有参考文档，以记录新功能或 API 变更

对于定期审查，可将最近合并的 PR 视为文档偏差的线索。检查这些 diff，然后在更新文档之前验证当前代码。合并本身并不要求更新随库附带的技能；请应用 lib/streamlit/.agents/skills/AGENTS.md 中的重点和范围规则。

随库附带技能更新的常见触发因素：

• 新增 st.* 命令或组件
• 现有命令的参数变更
• 已弃用的 API 或模式（添加警告，删除过时示例）
• 新的布局或主题能力
• 与性能相关的变更（缓存、片段）

快速验证命令

# Check path exists: test -e path && echo ok || echo missing
# Check URL reachable: curl -sI -o /dev/null -w "%{http_code}" <url>

工具版本来源

工具	配置文件
TypeScript、React、Vite、Vitest、ESLint、oxfmt、Emotion	frontend/package.json
Yarn	frontend/package.json（packageManager 字段）
Python、Ruff、mypy、pytest	pyproject.toml
Node.js	.nvmrc

问题类型

类型	描述
OUTDATED	信息已不再准确（旧的 make 目标、已重命名的文件）
INCORRECT	事实错误（错误的路径、无效的命令）
VERSION_MISMATCH	文档中的版本与实际不符
MISSING	重要信息未记录。不要标记已由 lint、format、type-check、Knip 或 CI 强制执行的约定。
REDUNDANT	重复陈述已由 lint、format、type-check、Knip 或 CI 强制执行的约定
BROKEN_LINK	链接指向不存在的资源
INCONSISTENT	与其他文档冲突

工作流

1. 枚举：查找所有 markdown 文档文件
2. 验证：将文档中的命令、路径和示例与代码库进行交叉比对
3. 报告：按优先级分组呈现发现的问题
4. 修复：在用户批准后应用更改

呈现发现的问题

列出所有问题，让用户选择要修复哪些：

Documentation Review: {SCOPE}
═══════════════════════════════════════════════════════════════

Found {N} issues across {M} files:

1. [OUTDATED] AGENTS.md:42
   Current:  `make python-check`
   Actual:   Command renamed to `make python-lint`

2. [INCORRECT] wiki/testing.md:15
   Current:  Tests in `lib/tests/unit/`
   Actual:   Path is `lib/tests/streamlit/`

3. [BROKEN_LINK] CONTRIBUTING.md:88
   Current:  Link to `./docs/setup.md`
   Actual:   File does not exist

4. [REDUNDANT] frontend/AGENTS.md:20
   Current:  Documents a specific oxlint/eslint/ruff rule (e.g. type-only imports)
   Actual:   Already enforced by lint/CI; omit from docs

Which issues should I fix?
Recommended: "all"
Options: "1" | "1,2,3" | "all" | "skip 3"

规则

• 提出建议前先验证：在建议修复之前，务必先检查代码库
• 最小改动：只更改实际有误的内容
• 保持所有文档精炼且简要：并非代码库的每个细节都需要记录。仅当信息与开发者的决策、正确用法、维护或预防可能的错误相关时才添加；不要仅仅为了完整性而用细枝末节扩充文档。
• 不要记录已由 CI 或 linting 强制执行的约定：如果格式化工具、linter（ruff、oxlint、eslint）、类型检查器、Knip 或其他 CI 检查已经会使某项约定失败或自动修复，则不要添加它；如果它已被记录，则将其删除。在将某项约定视为冗余之前，先确认所提及的规则存在且已启用。Agent 和开发者无论如何都会看到工具报错。只记录工具消息未解释的判断取舍、例外情况和"应改用何种方式"。如何运行这些工具（make 目标、何时使用它们）仍然有用。
• 优先采用持久、高层次的描述：简要描述 make 命令和工作流，说明其目的、触发条件以及何时使用。避免记录单个实现步骤、选项或机制，除非它们对正确使用或维护很重要。
• 测试命令：在记录命令之前先运行它们
• 保持风格一致：与现有文档风格保持一致

完成审查后

1. 向用户呈现所有发现的问题
2. 在做出更改前获得批准
3. 逐步应用修复
4. 运行 /checking-changes 进行验证

示例摘要：

Fixed 3 of 4 issues:

- #1 [OUTDATED]: Updated make command in AGENTS.md
- #2 [INCORRECT]: Fixed test path in wiki/testing.md
- #3 [BROKEN_LINK]: Removed dead link in CONTRIBUTING.md
- #4 [INCONSISTENT]: Skipped - requires manual verification

Files modified:
  AGENTS.md         |  2 +-
  wiki/testing.md   |  4 ++--
  CONTRIBUTING.md   |  1 -