docs(structure): 梳理清减 docs/ 结构并兑现 AGENTS.md 引用承诺#241
Merged
Conversation
- 修复 docs/arch/vendors.md 第 4 行的 framework.md 断链路径（./ → ../） - 补全 docs/agents/knowledge-map.md 占位为真正的项目文档索引（兑现 AGENTS.md L51 承诺） - 新建 docs/agents/browser-validation.md 完整浏览器验证协议（兑现 AGENTS.md L49 承诺） - 迁移 docs/ci-cd.md 至 docs/ops/ 子目录，建立运维向正交分类 🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist) Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
GitHub Markdown 渲染视图不为列表项生成行号锚点，#L49/#L51 等后缀无法定位到目标位置。 统一改为 §名称 前缀 + 纯文件链接，保留人眼可读性。 🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist) Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
背景与动机
docs/在 commit209f065（"拆分文档规范为独立文件并优化引用结构"）后已具备良好的"用户向 vs 架构向"正交基底，但仍残留三类完整性熵增：docs/arch/vendors.md:4的[framework.md](./framework.md)路径错误（应为../framework.md），以及AGENTS.md:49引用的docs/agents/browser-validation.md文件实际不存在。docs/agents/knowledge-map.md仅 3 行(WIP)占位，但AGENTS.md:51已对外承诺"项目所有文档索引统一维护在 knowledge-map.md"。docs/ci-cd.md（834 行运维流程）与user-guide.md（用户向）/framework.md（架构向）同级平铺，语义分类模糊。本 PR 在不扰动外部锚定文件的前提下，聚焦"修复 + 兑现 + 归位"三件事。
变更内容
docs/arch/vendors.md./framework.md→../framework.md，与同目录其他 5 个 arch/*.md 引用形式对齐docs/agents/knowledge-map.mddocs/agents/browser-validation.mddocs/ci-cd.md→docs/ops/ci-cd.mdgit mv迁移docs/ops/子目录承接运维向文档，与既有guide//arch//agents/四维正交；内部 5 处../xxx引用同步调整为../../xxx边界与未触动
严格规避对外部锚定文件的扰动：
README.md/AGENTS.md/CLAUDE.md/docs/zh-CN/*/docs/user-guide.md/docs/framework.md/docs/issue.md/docs/guide/*/docs/arch/*（除 vendors.md L4） /docs/agents/reference-specifications.md均未修改。原因：被README.md/AGENTS.md多处引用或属于设计意图（i18n 镜像），改名/移动成本远高于收益。验证
docs/*全部引用解析 OK（含原 MISSING 的browser-validation.md与原占位的knowledge-map.md）knowledge-map.md21 条内部链接全部解析 OK（含跨级../../README.md/../../AGENTS.md）git mv保留 ci-cd.md 历史（rename 相似度 98%）量化
docs/ops/）已知遗留（非本 PR 范围）
docs/ops/ci-cd.md引用../../.github/workflows/promote.yml，该文件实际不存在（pre-existing 问题，迁移前路径同样指向不存在的文件）。建议后续单独 issue 跟进promote.yml文档与实现的偏差。