Skip to content

docs(site): 旧长篇正名为「深度参考」并修正文档计数口径 (#167)#194

Merged
g1331 merged 2 commits into
masterfrom
docs/legacy-rename-167
May 29, 2026
Merged

docs(site): 旧长篇正名为「深度参考」并修正文档计数口径 (#167)#194
g1331 merged 2 commits into
masterfrom
docs/legacy-rename-167

Conversation

@g1331
Copy link
Copy Markdown
Owner

@g1331 g1331 commented May 29, 2026

背景

issue #167 收尾过程中,原计划清退 docs/ 根目录两个旧长篇(cliproxy-deployment.mdcircuit-breaker.md)。落地前用对抗性覆盖验证 + 引用核查,发现该计划的前提是错误的。

核实结论

两个旧长篇都不是待清退遗留,而是文档体系有意分层的深度参考

旧长篇 被新文档引用 新文档未覆盖的独有内容
cliproxy-deployment.md 8 篇 / 9 处 外部 CLIProxyAPI 部署步骤、卷备份迁移命令、bind mount 变体
circuit-breaker.md 8 篇 / 11 处 force-open/close 响应体结构、UI 三色徽章语义、两类故障排查、最佳实践

新文档大量以「详见现有长篇 docs/xxx.md」指回旧长篇(例如 circuit-breaker-config.md 开篇即写「状态机本身的转移规则、与 failover 的协同详见现有长篇 docs/circuit-breaker.md;本页只补全实际配置层面的三块内容」)。删除任一篇会同时破坏 8~11 处内链并丢失实质内容。

由此撤销 issue #167 收尾清单(#issuecomment-4554968662)中「旧长篇 + legacySidebar 清退」一项——该判断建立在未核实引用关系的错误前提上。

改动

保留两篇旧长篇,仅修正命名与计数口径,使其与真实角色一致:

文件 改动
docs/.vitepress/config.ts legacySidebarreferenceSidebar;侧栏分组「现有长篇」→「深度参考」;条目去掉「(旧版长篇)」后缀,改为「CLIProxyAPI 部署详解」「熔断器与失败转移详解」
docs/index.md 「部署 10 / 使用 13 / 架构 11 共 34 篇」精确计数改为按类组织 + 含 2 篇深度参考的表述,消除增删文档时的口径漂移
docs/en/index.md 同步去掉「34 documents」硬编码

3 files changed, 6 insertions(+), 6 deletions(-),纯文案与命名,无逻辑改动。

校验

  • 本地 pnpm docs:build 通过(build complete in 13.73s),sidebar 命名修改未破坏构建,无新增死链报错
  • pre-commit 全过(prettier / tsc)

Test plan

  • CI Build VitePress site 通过
  • 文档站左侧「深度参考」分组正常展开,两条链接可达
  • 首页底部计数表述与英文首页 language status 渲染正常

Related

issue #167 文档体系收尾。前序:#189(文档站本体)、#192(P0 stale copy)、#193(README 减负)。

核实发现 docs/cliproxy-deployment.md 与 docs/circuit-breaker.md 被新文档
内链引用 8~11 处,且含新文档未覆盖的独有内容(外部 CLIProxyAPI 部署步骤、
卷备份迁移命令、bind mount 变体、熔断 force-open/close 响应体结构、UI 三色
徽章语义、两类故障排查、最佳实践),并非待清退遗留,而是文档体系有意分层
的深度参考。

- config.ts: legacySidebar → referenceSidebar;分组「现有长篇」→「深度参考」;
  条目去掉「旧版长篇」后缀改为「详解」,使命名与真实角色一致
- docs/index.md: 「部署 10 / 使用 13 / 架构 11 共 34 篇」精确计数改为按类
  组织 + 含 2 篇深度参考的表述,消除未来增删文档的口径漂移
- docs/en/index.md: 同步去掉「34 documents」硬编码

撤销 issue #167 收尾清单中「旧长篇 + legacySidebar 清退」一项——该判断建立
在「旧长篇是待废弃遗留」的错误前提上,源于未核实引用关系。
@codecov
Copy link
Copy Markdown

codecov Bot commented May 29, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.09%. Comparing base (bf1f209) to head (b171d02).
⚠️ Report is 3 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files
@@           Coverage Diff           @@
##           master     #194   +/-   ##
=======================================
  Coverage   74.09%   74.09%           
=======================================
  Files         147      147           
  Lines       11115    11115           
  Branches     3847     3847           
=======================================
  Hits         8236     8236           
  Misses       1677     1677           
  Partials     1202     1202           
Flag Coverage Δ
verify 74.09% <ø> (ø)
🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

文档站面向使用者,让访客跳转到 GitHub issue 查看「撰写背景与版本规划」
属于维护者视角,突兀。

- docs/index.md: 删去首页尾部「文档结构、撰写背景与版本规划参见 issue #167」
- docs/guide/architecture/i18n.md: 「完整英文化由 Issue #167 的后续阶段跟进」
  改为「作为后续阶段的工作推进」,去掉 issue 链接
@g1331 g1331 merged commit 25d7d5f into master May 29, 2026
14 checks passed
@g1331 g1331 deleted the docs/legacy-rename-167 branch May 29, 2026 15:38
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