doc-initlisted

# 文档体系初始化（doc-init） 执行分两个阶段：**先修复全局规范，再初始化项目文档**。 `<DOC_INIT_DIR>` = 当前 `SKILL.md` 所在目录（动态解析，禁止写死绝对路径）。 --- ## 内置脚本速查 优先用内置脚本完成机械动作，把模型上下文留给业务判断： | 脚本 | 用途 | |------|------| | `scripts/project_inventory.py` | 扫描语言栈、构建文件、子模块、文档、配置、入口候选；只产出候选事实，不决定业务域 | | `scripts/doc_coverage.py` | 覆盖度闸门：代码功能入口 vs 地图锚点匹配 + 指纹基线，退出码 `COMPLETE(0)/STALE(2)/NEEDS_INIT(3)` | | `scripts/upsert_agents_nav.py` | 幂等新增或更新根 `AGENTS.md` 文档导航条目 | | `scripts/doc_nav_lint.py` | 检查根 `AGENTS.md`、`CLAUDE.md`、`docs/` 导航一致性 | | `scripts/db_miner.py` | 数据库 catalog 和领域级表/字段证据挖掘 | | `scripts/git_history_miner.py` | 轻量 Git 历史弱信号挖掘（热点、历史叫法、Q&A 线索）| | `scripts/depth_scanner.py` | 深度知识提取：状态机、并发、幂等、事件、实体字段等模式 | | `scripts/insert_doc_governance.py` | 版本检测 + 自动插入/升级全局 AI 指令文件中的「项目文档管理」章节 | 脚本输出是证据和防呆，不替代模型对业务边界、主称谓、KB/Guide 粒度和落档内容的判断。 --- ## 阶段一：校验并修复全局 AI 指令文件 ### Step 1 — 定位全局 AI 指令文件真身 探测以下文件，软链则跟到真身（`readlink -f`），对真身路径去重后得到待处理文件列表： 1. `~/.claude/CLAUDE.md` 2. `~/.codex/AGENTS.md` 3. `~/.codex/instructions.md` 4. `~/.config/opencode/AGENTS.md` 若均不存在，报告并询问用户路径后继续。 **禁止**把当前项目的 `AGENTS.md` 传给 `insert_doc_governance.py`——只处理上方列出的全局文件。 ### Step 2 — 脚本校验并自动插入/升级 对每个真身文件运行： ```bash python3 <DOC_INIT_DIR>/scripts/insert_doc_governance.py "<真身路径>" ``` | 输出前缀 | 含义 | 后续动作 | |----------|------|----------| | `[跳过]` | 已是最新版本 | 直接进 Step 3 | | `[新增]` / `[完成]` | 首次插入成功 | 进 Step 3 | | `[升级]` / `[完成]` | 旧版已替换 | 清理散落旧规则，再进 Step 3 | **仅在 `[升级]` 时需要模型额外清理**（扫描并删除）： - `## AGENTS.md 优先级` 整个章节 - `知识持久化` 章节下的 `### 检索在先、存储在后