Skip to content

docs: 全面同步过时文档至当前代码状态#197

Merged
g1331 merged 2 commits into
masterfrom
docs/refresh-stale-docs
May 30, 2026
Merged

docs: 全面同步过时文档至当前代码状态#197
g1331 merged 2 commits into
masterfrom
docs/refresh-stale-docs

Conversation

@g1331
Copy link
Copy Markdown
Owner

@g1331 g1331 commented May 30, 2026

背景

通过多代理逐篇对照源码,全量核查了仓库 43 篇活跃文档(README、docs 站点、openspec/project.md、PR 模板、VitePress 配置)与当前代码的一致性。诊断结论:3 篇 broken、14 篇 stale、17 篇 minor、9 篇本就准确。本 PR 修复其中 33 篇 + CLAUDE.md。

主要修复

整体错误

  • openspec/project.md:此前整篇是 FastAPI + Next.js monorepo 脚手架模板(apps/api、uv、Ruff、Pyright、Alembic),与实际单体 Next.js AI 网关完全不符,已按真实技术栈、架构、测试策略、约束重写。
  • docs/.vitepress/config.ts:footer 许可证 MIT → AGPL-3.0(与 LICENSE 一致)。
  • CLAUDE.md:补齐双方言数据库、Playwright E2E、计费/cliproxy/流量录制/后台同步服务层、能力路由、真实 CI 检查项与端口。

行为/语义事实错误

  • circuit-breaker.md:熔断默认值 openDuration 30s→300s、probeInterval 10s→30s;配置示例由错误的 config.circuit_breaker 包装改为真实的顶级字段 circuit_breaker_configJSONBJSON
  • request-lifecycle.md:删除不存在的 status: in-progress 字段;模型匹配模块 model-router.tsfilterCandidatesByModelRules
  • security.mdrevealApiKey 路径 auth.tskey-manager.ts
  • model-routing.md:alias 精确匹配语义、GET /chat/completions 实际被拒、补充 streamGenerateContent 路径。
  • circuit-breaker-config.md:失败规则端点方法 GET/PATCHPUT/DELETE
  • troubleshooting / quickstart:缺 ADMIN_TOKEN 不会导致启动失败(返回 401),更正该排障描述。
  • env-reference / admin-overviewRECORDER_FIXTURES_DIR 代码默认值 data/traffic-recordings 与 docker-compose 默认 tests/fixtures 的区分;CORS_ORIGINS 当前仅解析、无运行期效果。
  • i18n / database-schema:翻译 namespace 数量补 livePulse、迁移文件计数更正。

行号同步

架构与使用文档中大量随代码增长漂移的源码行号引用,每篇均由修复代理重新 Read 当前代码核对后更正(而非套用诊断估算值)。

校验

  • 全部改动文件通过 prettier --check
  • 两个提交均通过 pre-commit(含全量 tsc --noEmit)。

范围说明

未改动 openspec 归档变更(changes/archive/**)、进行中的变更提案与 specs 规格库——它们是历史/工作流管理的快照,不属于「与代码同步」的范畴。

g1331 added 2 commits May 30, 2026 16:51
补齐双方言数据库(PG/SQLite)、Playwright E2E、计费/cliproxy/流量录制/
后台同步等服务层、能力路由模型、真实 CI 检查项与默认端口等已偏离的内容。
经多代理逐篇对照源码核查 43 篇活跃文档,修复 33 篇的事实性偏差:

- openspec/project.md:整篇重写,此前为 FastAPI+Next.js monorepo 脚手架
  模板,与实际单体 Next.js 应用完全不符。
- docs/.vitepress/config.ts:footer 许可证 MIT 更正为 AGPL-3.0。
- docs/circuit-breaker.md:熔断默认值 openDuration 30s→300s、probeInterval
  10s→30s;配置示例改为真实的 circuit_breaker_config 顶级字段;JSONB→JSON。
- request-lifecycle.md:删除不存在的 status:in-progress 字段描述,模型匹配
  模块由 model-router.ts 更正为 filterCandidatesByModelRules。
- security.md:revealApiKey 路径 auth.ts 更正为 key-manager.ts。
- model-routing.md:alias 精确匹配语义、GET /chat/completions 不支持、补充
  streamGenerateContent 路径。
- circuit-breaker-config.md:失败规则端点方法 GET/PATCH 更正为 PUT/DELETE。
- troubleshooting/quickstart:缺 ADMIN_TOKEN 不致启动失败的行为更正。
- env-reference 等:RECORDER_FIXTURES_DIR 代码默认值、CORS_ORIGINS 无运行
  期效果等说明补正。
- 架构与使用文档中大量随代码增长漂移的源码行号,按当前代码重新核对更正。
- README/README_EN:TypeScript 徽章版本对齐主版本约束。
@g1331 g1331 merged commit dbcb5fe into master May 30, 2026
14 checks passed
@g1331 g1331 deleted the docs/refresh-stale-docs branch May 30, 2026 15:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant