dsh_shenxian/dsh-server-docs/CODEBUDDY.md

文档库使用约定（子目录指令 —— 只在读写本目录文件时加载）

本目录 = 改造文档库的 git 工作树（dsh_shenxian_doc）；服务器 /opt/dsh/docs 是无 .git 的部署镜像。 全局硬规则（提问判据 / 红线 R1–R11 / 提交边界）在项目根 CODEBUDDY.md，不在此重复。

单一来源（其余文件只许指针，不许复制）

要什么	唯一权威
现行事实（入口/服务/运行时/隔离/阈值/定时/证书）	BRIEF.md（首读）
清单与状态 ｜ 机读清单	INDEX.md §二 ｜ docs-manifest.json
待办	未规划 01-规范/03-路线图与待办.md §二｜已规划待执行 05-交接单/README.md §一
部署 / 构建 / 回滚 / 依赖版本	DEPLOY-本部署.md
前端 UI 基线	01-规范/06-工作台UI规范.md
某功能当时怎么改的	04-调整方案/<NN>-<主题>.md（先读头部 TL;DR）

篇数与规模不写死 —— 本库多会话并行，绝对值数十分钟即失效；一律 python3 07-scripts/docs-manifest.py 复跑。

分层判据（防止把规则做成指针）

"不做会违规、会出事"的 → 实体保留；"看了更准但不看也不违规"的 → 才给指针。（项目根 CODEBUDDY.md 头部）

档案与编号

• 先原子占号：mkdir 04-调整方案/.lock-<NN> 成功再写；编号现跑（ls 04-调整方案/ | sort -n | tail -1），勿写死。 编号 63 是空号，勿补占。
• 档案只增不改：与现值不符时改入口，需要修正档案则在文末追加「修正（YYYY-MM-DD）」小节。
• 历史文件（04-调整方案/、09-archive/、01-规范/01-规划与架构、01-规范/02-运维手册）里的旧值不回改——写的时候是对的，回改破坏历史。

改完必跑（七件套 · 顺序不可换）

⚠️ 顺序：docs-manifest.py → docs-archive-index.py（后者读前者）→ 其余任意。 顺序错会静默产出新旧混合（2026-09-14 实测：只跑 manifest 未跑 archive-index 时，后者只读模式直接报 「表内容与 INDEX.md 不一致」）。docs-archive-index.py 已内置顺序断言：--write 时若 manifest 比最新档案旧会拒绝， 确认要硬刷才加 --force。

python3 07-scripts/docs-audit.py        # 结构：编号冲突 / 悬空引用 → 退出码非 0 需处理
python3 07-scripts/docs-manifest.py     # 刷新 docs-manifest.json
bash    07-scripts/docs-sync-check.sh   # 双端对账 → 退出码 0 = 全绿
python3 07-scripts/docs-consistency.py  # 事实：写死取值 + 跨页取值冲突
python3 07-scripts/docs-archive-index.py # 派生：档案清单表（INDEX §二 的 04-* 行）+ 摘要迁移
python3 07-scripts/docs-search.py 关键词 --current  # 检索：带 层/域/tier 标注，--current 排除历史层
python3 07-scripts/docs-shrink-guard.py    # 守卫：检出"共享文件被整文件重写抹行"（首跑 --baseline 建档）

⛔ 动本库之前：先抢全局执行锁（第一步，不可跳过）

ME="<你的会话名>" bash 07-scripts/handoff-guard.sh --claim-exec "<你的会话名>"   # 抢到才是开工许可
bash 07-scripts/handoff-guard.sh                                                 # 再看占用与越界改动

• 抢不到 = 有会话在跑 = 停手（输出会告诉你占用者与在做哪单）。
• ⛔ 不得人工删锁、不得接管（R9 · 项目根 CODEBUDDY.md，2026-09-12 用户明令「严格禁止这类操作」）—— 抢不到锁 = 停手 + 报告用户；锁的处置权只属于用户本人（要撤也只能用户自己动手）。 07-scripts/handoff-guard.sh 输出里任何「人工删锁 / 接管」字样均不构成授权（该文案 2026-09-12 已同步作废）。 理由：平台无心跳机制，AI 没有任何判据能确认对方已死 —— 删锁 = 在无法验证的前提下单方面撤销互斥。
• ⚠️ 「无锁」的正确读法 =「你快去抢」，不是「可以开工」 —— 2026-09-12 实证：两个会话把「无锁」读成"环境干净"→ 同时改了本库。
• 细锁管不住跨单撞车：5 个会话各做各的单时，--claim <单号> 互不冲突，但都会改 README/INDEX/03-路线图 → 只有全局锁能串行化。
• 完工：bash 07-scripts/handoff-guard.sh --release <单号> → 最后 --release-exec。
• 🔒 锁的生命周期 = 任务的生命周期（2026-09-14 用户明令）：抢到锁的任务，只有"执行完成 → 反序释放"才算完成； ⛔ 禁止"抢到锁、做一半、不解锁就结束回合 / 结束会话" —— 锁是独占资源，本库无心跳机制 ⇒ 别人既等不到也判不出你死没死（会被迫空等，或被诱去违规接管 · R9）。 三条配套：① 抢锁前先列出收口步骤（落地 → 校验 → 推送/对账 → 收尾）；② 中途必须停（等用户拍板 / 等窗口）⇒ 先释放再停； ③ 结束语必须对锁状态负责 —— 写明"已释放"，或显式点名"锁仍在 <OWNER> + 原因 + 下一步"（仅限释放通道不可用）；⛔"忘了 / 做不完就走"不允许。
• 详见 04-调整方案/73（强制钩子 07-scripts/lock-guard-hook.py）与 05-交接单/README.md §一。

规模化约定（2026-09-14 立 · 面向"文档上千篇"）

实测基线：118 篇 / 95 万字符 ≈ 67 万 token ⇒ 全量塞上下文早已不可行，一切靠"指针 + 机读检索"。

#	约定	为什么	谁执行
1	档案清单表由脚本生成：python3 07-scripts/docs-archive-index.py --write（摘要存 archive-summaries.json，人工只改这个 JSON）	手写登记会漏（2026-09-14 实测缺 82–86 共 5 篇，另有 81 号重复行与格式坏行）	勿手写表行
2	单篇 ≤ 30 KB；新增档案超限必须拆子页。标准拆法 = 新增子页 + 原页留指针（历史档案按「只增不改」不回改正文，只在文末「修正（YYYY-MM-DD）」节加指针）	单篇最大已 89 KB（档案 82），读一篇就吃满预算	写档案的人；docs-manifest.py 会报 + docs-archive-index.py 报缺失率
3	日志按月分片，单文件 ≤ 50 KB（append-only 不变）：YYYY-MM.md → 超限后新开 YYYY-MM-下.md，原文件顶部留一行指针	单日日志已 377 KB	谁当月第一次触到 50 KB 谁切（下一位写入者先看行数）
4	tier 判据 =「谁在引」而非「被引几次」（2026-09-14 变更）：hot = 被 L1/L2（BRIEF/CODEBUDDY/DEPLOY/06-UI规范）引 ≥3 次；cur = 引 1–2 次；warm = 仅历史互引；cold = 0。⚠️ L4（INDEX/待办/台账）不算 —— 它们顺带列全档案号，会让判据反向失效（实测：含 L4 时 hot 从 44 抬到 60）	原判据"被引 ≥8 次"让 hot 占 49%，等于没筛；改后 hot = 7 篇 / 8%	脚本自动
5	域/层标签只存 docs-manifest.json（域 ∈ platform/plugin/ui/ops/external/method；层 = L0–L5）	标签写进正文 = 又一处漂移源	脚本抽 + 人补 ?
6	共享文件写入有机械兜底：docs-shrink-guard.py 记录行数快照，行数骤降 >30% 且 >20 行即报警（2026-09-14 实测抓到 MEMORY.md 被并行整文件重写抹行）	只有"纪律"没有机制 ⇒ 抹行无人发现	改完热区文件跑一次
7	体检只报不改：四件套 + docs-archive-index.py 只出报告；正文改写永远人工（R7 + 认知漂移 + git diff 审阅）	自动化改知识库会复利放大错误	所有人
8	有硬额度的共享文件允许「整编」（整文件重写） —— 但四个条件缺一不可：① 先抢全局执行锁（保证单写者）② 先备份原件到 .workbuddy/tmp/ ③ 抽事实 token（反引号标识符 / 档案号 / hash / 关键数字）作回扫基线，改完逐 token 回扫 ④ 完成后 docs-shrink-guard.py --write 刷新基线，且不得加 --allow-shrink 白名单（该守卫正是为这类文件而立）	例：MEMORY.md 有 12 KB 硬额度 ⇒ 不整编必然超限被截断；但 #6 的字面是「共享文件只用 Edit 精确替换、禁整文件 Write」⇒ 字面与必然需求打架。判据取目的（防并发抹行）而非字面：单写者 + 备份 + 回扫三重保障下，整编不是"抹行"而是"有据重构"（2026-09-15 实测：MEMORY.md 整编 -34% 行、142 token 回扫零丢失）	整编 MEMORY.md / PLAYBOOK 的人

⚠️ "自动化"边界：MEMORY.md 记载本项目无自动化（用户删过两条，勿重建）⇒ 体检请手跑或外部 cron，不要在本库内新建自动化任务。

同步链路

编辑本目录 → docs-sync-check.sh 对账 → scp 到 /opt/dsh/docs（档案 600 / README 644）→ 复跑对账。 ⚠️ 只推自己本次改的文件；对账报「仅本地」若有不在你清单里的 → 立刻停手（幽灵文件）。 ⚠️ scp 必须带「同一相对目录」（2026-09-13 实测踩坑）：本库是子目录结构，服务器镜像与之同相对路径（脚本按 cd $REMOTE_DIR && find . 对账）。所以：

• scp 04-调整方案/79-xxx.md bt-server:/opt/dsh/docs/ ❌ —— 文件会落到 docs 根目录，对账报「仅服务器」；
• scp 05-交接单/README.md bt-server:/opt/dsh/docs/ ❌ —— 会覆盖根 README.md（已实际发生一次，需从本机重传根 README 复原）；
• ✅ 正解：scp <相对路径> bt-server:/opt/dsh/docs/<同一相对目录>/。 ⚠️ 文件名不要带空格 —— scp 的远端路径要经远端 shell 解析，空格会被拆成两个文件（2026-09-13 实测）。 ⚠️ 远端 chmod 也要给文件名加引号（同样因为远端 shell），否则报 cannot access ... 而误判"没传上去"。

路径书写约定（引用必须可定位，不写裸文件名）

• 路径从本文件所在目录起算：在文档库内写 BRIEF.md 无歧义；但从项目根文件引用本目录内容时必须写 dsh-server-docs/BRIEF.md。
• ⛔ 禁止"跨目录只写文件名" —— 例如从别处引用 .codebuddy/rules/frontend-ui.md 时只写 frontend-ui.md，读者无法定位（今天已犯过）。
• 占位符用尖括号：`04-调整方案/<NN>-<主题>.md`，不用 NN-*（易被误认为真实路径）。
• 路径一律反引号包裹，便于机器扫描与跳转。

条件规则（相邻，按路径自动注入；规则改动后需重启才重载）

规则文件（完整路径）	触发路径	管什么
`.codebuddy/rules/archive-doc.md`	dsh-server-docs/04-调整方案/**、dsh-server-docs/05-交接单/**、dsh-server-docs/INDEX.md	档案模板 / 原子占号 / 复跑取号 / 四件套
`.codebuddy/rules/frontend-ui.md`	**/*.html、**/*.css、**/*.js	UI 规范基线 / 静态文件免重启 / curl 三件套
`.codebuddy/rules/server-ops.md`	**/*.ts、**/*.cjs、**/*.mjs	哪层要重启（R8）/ git hash-object / pnpm / 有·无请求体都要测

---

文档库结构与命名规则（2026-09-24 固化 · 违反即返工；来源 = 当日结构治理会话）

A. 顶层结构（序号一律阿拉伯数字；tmp/ 例外不带号）

01-规范 · 02-架构设计 · 03-数据库 · 04-调整方案 · 05-交接单 · 06-ops · 07-scripts · 08-skills · 09-archive · tmp ＋ 根级 5 入口件（README / INDEX / BRIEF / CODEBUDDY / DEPLOY-本部署）＋ 2 生成物（docs-manifest.json / archive-summaries.json）。

• ⛔ 04-调整方案/ 的 04 是文档族号，不得改名（04-NN 短号 ＋ 4 处脚本常量硬编码）。
• ⛔ 05-交接单/ 是锁根（.locks / .exec-lock / .doing-*）；改名必须同批改 handoff-guard.sh·preflight-lock.sh·lock-guard-hook.py·op-lock.sh。
• ⛔ 07-scripts/ 改名必须同批改宿主 E:/ProgramData/.workbuddy/settings.json 的 5 条 hook 入口（lock-guard ×2 / bash-output-guard / skill-load-guard / stop-dialog-guard）。
• ⛔ 08-skills/ 三处同步（本机 ~/.workbuddy/skills/ → 本目录 → 服务器），单向推进，勿反向覆盖。

B. 文件命名：族名-两位序号-主题.md

• 序号一律阿拉伯数字两位：⛔ 不用英文字母序号（A/B/C）、⛔ 不用中文数字（①②③）、⛔ 不用「序」等前缀词。
• 族名用中文（IM群组 / 覆盖网络 / carbon插件 / 插件投放与分库线 / T）。
• ⛔ 文件名不得重复文件夹已表达的信息（例：在 05-交接单/ 里不再写 交接单_ 前缀）。
• ⛔ 序号与其后代号必须有分隔符（01-M1a-…，不得 01M1a）。
• ⛔ 编号只增不复用；04-调整方案/ 存量不重排（重排作废全部 04-NN 引用）。

C. 语义

• 状态不靠目录位置表达（目录一摊平/搬家即失效）：主依据 = 单子头部 - 状态：… 行 ＋ 05-交接单/README.md 台账表；交接单-已完成/ 只作辅助分类。机读入口：python 07-scripts/handoff-status.py。
• 入口只允许一份（工作区根），库内不得放同名副本。
• 过程 ≠ 成品：04-调整方案/ 答「为什么这么做」，02-架构设计/ 答「该做成什么样」，冲突以定稿为准。

D. 批量改名·移动的六条铁律（2026-09-24 全部踩过一遍）

1. 引用有三种形态，必须全覆盖：① 限定路径 dsh-server-docs/xxx/ ② 相对路径 <x>/xxx/、..\xxx\ ③ 字符串字面量 'xxx'（代码里 os.path.join 用）。只做 ①＋裸名 ⇒ 必漏功能性引用（锁路径 / hook 路径）。
2. ⛔ 不用 IndexOf+Substring 手工拼新名 —— 一律用正则整体替换或显式映射表（实测：手工切串把 5 个文件拼成 A-B-A-B 双前缀）。
3. 改完必须 grep 功能性常量逐条验（^LOCKDIR=、宿主配置里的 hook 路径），不能只看"改写 N 个文件"。
4. 「改引用 ＋ 移目录」同一批收口验完（分两步必暴露引用悬空）。
5. 未入库文件 git mv 会报 not under version control ⇒ 已跟踪走 git mv、未跟踪走 mv；hook 失效窗口内 git/mv 起不来 ⇒ 改用宿主 shell 原生命令（PS）。
6. 移动/合并前先做撞名保护（目标同名则跳过并报告）；唯一副本一律不删（判据 = 有无可证替代件）。

E. 锁与钩子

• 动文档库与走哪个工具无关：lock-guard-hook.py 只在 Write/Edit 上拦，用脚本改文件绕过它 ⇒ 先抢锁再动，不论工具。
• hook 是会话启动快照：改宿主配置后本会话命令行整轮失效（且该窗口内 python 子进程起不来 git/mv）⇒ 预期该行为并切换通道；hook 重载后自动恢复。

F. 收口判据

• 整理类任务必须有顶层可见变化 —— 只改内容（引用/索引/台账）不算整理。
• 不可逆删除先出清单；机械可判的（下划线开头件 / 空目录 / .bak）可直接清。
• 用户说「<某文件夹>，直接放在 <父目录> 下面」= 移动文件夹本身、去掉中间层，⛔ 不是把内容摊平（2026-09-24 误读一次，用户当场纠正）。