dsh_ai1net_server/交付物/项目开发-任务执行关键步骤-20260929.md

项目开发 · 任务执行关键步骤（全文版）

🔴 每个会话、每个任务都必须按本顺序执行；跳步＝违规。 实体精要已在 CODEBUDDY.md §1.5（那份每次会话自动加载，冲突以 CODEBUDDY.md 为准）；本文是全文版（命令、判据、坑）。 权威来源：CODEBUDDY.md（根规）＋ 技能 dsh-workflow → references/00-平台改造六阶段.md（六阶段原文）。

---

0 一句话总览

开工前三件 → 六阶段（0 需求识别 → 1 调研 → 2 规划 → 3 开发 → 4 验证 → 5 归档清理）→ 收尾四件。 其中三道硬门禁：抢不到锁 ⇒ 停手（R9）｜红线命中 ⇒ 先停手（R1–R11）｜交付门禁（本机改完 ≠ 交付）。

---

1 开工前三件（顺序固定，⛔ 不准换）

1.1 跑状态（1 次调用顶十几轮探索）

"$PY" "$WS/state.py"          # --online 加远端基线

🔴 跑完之前不许 Glob/Grep 全库摸底。 输出里看：[锁] / [git] / [入口]（它会展开本线接续入口的 §2）。

1.2 判可锁定范围（开工门禁）

bash "$DOC\07-scripts\preflight-lock.sh" "<会话名>" <目标文件...>

• 【A】可独立锁 ·【B】秒级独占 ·【C】共享（构建产物/依赖树）·【D】未归类 ·【E】机制层
• 🔴 【D】或【E】非空 ⇒ rc=1 拒开工：D 先归类再动；E（机制层：config·crypto·isolation·index·scripts·CODEBUDDY.md·锁与钩子本身）必须独占，且仅当确认无其他会话在跑才可开工。

1.3 抢锁（是"抢"不是"看"）

bash "$DOC\07-scripts\handoff-guard.sh" --claim-exec "<会话名>" [--domains <域键>]

• 域键 = <锚点段>/<下一段>，多个用逗号；⛔ 不带 --domains ⇒ 退化为全局独占（机制层必走）
• 🔍 必须"校验结果"不能"看输出"：① 检查退出码（⛔ 不接管道，| grep 会吃掉退出码）② 复读 .locks/<会话名>/DOMAINS 或 .exec-lock/OWNER 并断言是自己的
• ⚠️ rc=1 两因分清：域冲突（停手） vs .gate 占用（重试）
• ⛔ 抢不到锁 ＝ 终点：只读、报告、结束（R9：不删锁、不接管）
• ✅ 锁只约束「写」，不约束「读」；⚠️ 会改本地状态的命令（git fetch/checkout/stash/reset/switch）算写 ⇒ 要持锁

---

2 六阶段

阶段 0 · 需求识别（先盘点再动手，勿跳步）

0. ★ 开工前置检查 —— 本流程最重要的一步（血的教训：不先查"已经有什么"就凭直觉装工具/猜机制，事后才发现文档里早写了）。任何「装工具 / 写自动化 / 查机制」之前按序做完三条：
   1. 先看可用技能列表（会话开始就在）⇒ 有对应的立刻加载技能，禁止另起炉灶；
   2. 先看本机/项目已有资产：E:/ProgramData/.workbuddy/skills/（技能根，改动下一请求生效）、工作区 MEMORY.md；
   3. 要装任何东西前自问：本机已有的能否满足？ 能 ⇒ 不装；不能 ⇒ 先说清楚再装。
1. 环境盘点：本机 / 服务器 / 工具链 / 权限 / DB / 实例状态先行。
2. 需求边界：区分「方案请求」（只输出方案 —— 方案与执行分离，未经明确授权不改文件）与「任务明确直接执行」。
3. 用户确认：关键分叉用选项表收敛（推荐项置首）。
4. 输出格式：一句话结论先行 ＋ 表格化细节。

阶段 1 · 调研（源码级实证优先，⛔ 禁只靠文档推断）

0. ★ 用户报障第一步：先拿「真实失败请求」，别猜 —— 平台 journal 里有精确 URL + method + status：

   ssh ... 'journalctl -u dshs --since "-30min" --no-pager \
     | grep -E "401|403|404|500|502|503|crash-restart|YAMLException|ERR_MODULE" \
     | grep -v "level.:30.*200"'
   

   判据：401 先分辨平台 401 还是实例 401（改的地方完全不同）；502 = 实例没起来 ⇒ 翻同段 YAMLException / ERR_MODULE_NOT_FOUND / crash-loop。
1. 只读分析官方包（允许）：读 bundle 定位机制（slot 声明、inject 契约）。绝不写官方主程序。
2. 服务器实测 > 推断：区分 fence 层 / 应用层错误。
3. 双端对照：archive 源 ↔ 实例安装副本 md5 对账。
4. 多模型交叉验证：关键结论不轻信单点推断。

阶段 2 · 规划（文档先行，方案确认后动工）

1. 方案对比表：≥2 选项 ＋ 各自影响/风险 ＋ 建议。
2. 🔴 红线自查 R1–R11（逐条过；命中 ⇒ 先停手）。
3. 影响评估：重启换端口 / 旧连接断连 / 权限影响…；命中 R5（权限扩大）另附「权限影响评估」＋ 改动前后 diff。
4. 文档占位：04-调整方案/ 建编号档案 —— ⚠️ 档案号必须「原子占用」（mkdir .lock-$n 或 flock），⛔ 不能"读一眼 ls 再写"（已两次撞号）。

阶段 3 · 开发（小步 + 备份 + 逐条验证）

1. scp 服务器源码 → 本地 → 读一条 → 改一条 → 验一条（⛔ 禁批量读全部文件）
2. scp 回服务器 /tmp/ → cp 覆盖前先备份 bak-<功能>-<YYYYMMDD>/
3. npm run build（零报错）→ systemctl restart dshs
4. 本机直连验证（绕 DNS/代理）：curl -sk --resolve <域名>:443:127.0.0.1 https://<域名>/api/...

   ⚠️ 全量覆盖 lib/ 前必须先在 HEAD 上 build（曾把别人已上线的修复整体回退）；部署完立刻复验「上一次刚验收过的东西」。 ⚠️ 「已部署」≠「已提交」；不能拿服务器状态当版本事实源。

客户端插件（client bundle）另有链路：先做基线校验（拉线上 tgz ↔ 本地源码忽略行尾全量 diff，确认"差异只有我要改的"）→ 改 → npm pack → 铺 tgz（chown 用户 uid）→ kill 实例 → 抓新端口 → 验 node_modules 里 markers（版本、关键串计数）。⛔ 反例：先改后验（顺序错 = 风险窗口白开）。

阶段 4 · 验证（全链路 + 浏览器实测 + 清理）

1. API 链路：portal enter → url token → 页面 200 → 关键接口 ok。
   • 🔴 用例必须同时覆盖「有请求体」与「无请求体」（只测 POST 会整条漏掉 GET/SSE）。
   • 模拟浏览器语义要测到底：只带最初那个旧 cookie 再跑一遍，并显式断言 Set-Cookie 回写。
2. 浏览器验证栈：只用 browser-harness（⛔ agent-browser、Playwright 均已禁用）。
   • 🔴 铁律 0：动手前先 list_tabs() 确认"你在驱动哪个浏览器" —— ⛔ 不要假定端口号（端口归属每次都变）；看到的不是你新开的空浏览器 ⇒ 立刻停手，只做只读检查。收尾必须 close_tab 关掉自己开的标签。
3. 静态 vs 后端：改 web/*.html 无需重启；改 src/** 才 build + restart。⛔ 别为前端改动重启服务（会打断所有用户实例）。
4. 安全面复测：降权 uid 探测敏感目录应 denied；中间目录 711（去 r 留 x）不破坏子进程访问。
5. 清理临时物（poc-* 会话用完即删、测试 tab 关闭）。
6. 截图留证（每功能验收存 PNG ＋ 展示）。
7. 🔴 交付前必问一句：这份改动「出厂」了吗 —— 改完文件 ≠ 用户会看到变化。一秒自检：ls -la 对比「源文件 mtime」与「最新 tgz mtime」，源更新 ⇒ 还没出厂。
8. 视觉/UI 必须三层验收：① 单测（断言 class 名与结构，不只文本）② 实装（md5sum 对齐本地产物 ↔ 实例 node_modules 实链，断言旧标记为 0）③ 端到端（解出真实 bundle URL → curl 回来 grep 新/旧标记）。
9. 用户说"参考某现成页面的样式" ⇒ 抄那个页面的源码（逐条搬实际取值），⛔ 不要抄规范的抽象条目再自行演绎。

阶段 5 · 归档清理（文档同步 + 三层沉淀）

0. ★★ 交付门禁：本机改完 ≠ 交付。收尾前逐层自问三句：① 这次改的是哪一层？② 这一层的生效链路是什么？③ 最后一步走了吗、在「用户可见面」验了吗？

   改动所在层	生效链路（缺一步都不算交付）	用户可见面复验
   平台静态页	scp 到服务器对应路径（注意 CDN/CF 缓存）	curl 取线上页面确认新内容
   平台 TS（src/**）	npm run build → systemctl restart dshs	线上端点/页面实测（不是本地 build 通过）
   自研插件（client bundle / host 面）	打 tgz → 导入候选池 → 实例「功能管理」启用 → 重启实例	取实例页 HTML 里真实 bundle URL 逐串验证
   文档库 / 技能	docs-sync-check.sh 对账 → scp → 复跑对账	对账「一致」计数回升
   配置（env / nginx / nft / 配额）	改 → reload / restart 对应服务	生效值实测

   ⛔ 四条"自我安慰"一条都不算交付：本机改完了 / build 通过了 / 本地打包完成 / 已 commit 了。 ⛔ 也别回头问用户"要不要部署" —— 不打断在线用户的上线属我的 lane 内执行细节 ⇒ 直接做完（§3 R7-边界）。

1. 文档落盘：源 = 本地 D:\github\dsh_shenxian\dsh-server-docs（目录即 git 工作树）。 四件套（顺序固定）：docs-audit.py → docs-index-stats.py --write → docs-manifest.py → docs-sync-check.sh。 传服务器用单个 tar 管道（逐个 scp 会因每文件一条 SSH 连接而超时），随后 chmod（目录 700 / 文件 600）。 ⚠️ 本库多会话共用 ⇒ 提交前 git status，只 add 自己改的文件；docs-manifest.json 是派生文件，别人有在途改动时宁可让它 dirty。

2. 档案更新：04-调整方案/<NN>-*.md 写"需求→改动文件→commit→验证记录"；INDEX.md 同步（以它为准）。

3. 三层沉淀：治本（机制/流程固化进 skill 或档案）／失误（append-only 教训档）／记忆（AGENTS.md 或工作区规则）。

4. 汇总表：带状态/结果列交付，列明未完成项与副作用。

5. 技能自身归档（本 skill 有改动时必做）：本机 → 服务器单向推，md5 双端一致才算完成；同时更新引用它的 README 模块表行 / INDEX 场景速查行。 ⚠️ 改「跨载体规则」时必做全载体扫描（grep -rn 关键短语，把所有命中处全部改掉；只改一处 ⇒ 其余载体自相矛盾，比不改更糟）。

---

3 收尾四件（缺一不算完成）

1. 反序释放锁：先 --release，最后 --release-exec "<会话名>" —— ⛔ 不带会话名 ⇒ 拒绝释放 🔓 释放时机 = 交付闭环走完（台账 → 四件套 → commit → 推送 + 对账 → 归档），不是"改完就放"；要等用户拍板 ⇒ 先释放再等
2. 台账 / 档案（见阶段 5）
3. 提交边界：未明确要求 ⇒ 不 commit / 不 push / 不同步仓库；说了才做且只 add 自己改的文件； ⛔ 三类禁止入库：tmp/ ／ 中间产物 ／ 会话交接单。提交前自查 git diff --cached --name-only 命中即 git reset
4. 收口清本棒 tmp/；🔴 结束语必须对锁状态负责（写明"已释放"，或点名锁在谁手上 + 原因 + 下一步）

⛔ 禁"抢到锁、做一半、不解锁就结束回合"（带锁结束 = 把所有人挡在门外）。⚠️ 护栏额度耗尽时 release 可能 rc=124 卡住 ⇒ 用 mv 等效释放。

---

4 并行纪律（要点）

• 共享文件只用 Edit 精确片段替换（失败 = 天然冲突检测），⛔ 禁整文件 Write 覆盖；settings.json 的 hooks 段与用户级 MEMORY.md 只能增删条目，⛔ 禁整段覆盖
• 并行度由「冲突域」定，不由任务数量定：只读/调研可自由并行；改码 → 构建 → 重启 → 提交 → 写文档是单通道，必须串行
• 🔴 域键算法 shell 与 hook 两侧必须逐字一致（_ANCHOR_SEGS ⇄ _DOMAIN_SEGS），⛔ 改一侧 ⇒ 域锁静默失效（假绿）
• ⚠️ 钩子 = 会话启动时快照：对在跑的会话无效 ⇒ 改完要完全重启（关窗 ≠ 退出）；脚本路径失配 = fail-closed（Write/Edit 全被拒）

---

5 收尾自检清单（逐项打勾）

• 跑过 state.py？门禁 preflight-lock.sh 过？锁校验过是自己的？
• 阶段 0 的「开工前置检查」做了吗（先看技能/已有资产）？
• 红线 R1–R11 逐条过了吗？命中 R5 出了权限影响评估吗？
• 覆盖前备份了吗？**部署完复验"上一次刚验收过的东西"**了吗？
• 用例覆盖**「有/无请求体」**两类了吗？
• 交付门禁三句答得上吗？四条自我安慰有没有出现？
• 四件套跑了吗（顺序对）？只 add 自己的文件？
• 锁释放了吗（带会话名）？结束语点名锁状态了吗？
• 本棒 tmp/ 清了吗？