kld-sdd 2.7.8-7 → 2.8.0

package/lib/skills-bundle.js

@@ -18,7 +18,7 @@ const POWERSHELL_TABOOS = [
   '',
   '> - **PowerShell 禁忌**（Windows 用户必读）:',
   '>   - 禁止 `| cat`（PowerShell 将 cat 解释为 Get-Content，不接受管道输入）→ 直接执行命令',
-  '>   - 禁止 `node -e "..."` 内联脚本（PowerShell 对 `||`/`{}`/`()` 有特殊解析，导致 JS 语法被破坏）→ 用 `write_to_file` 创建临时 `.cjs` 脚本执行后删除',
+  '>   - 禁止 `node -e "..."` 内联脚本（PowerShell 对 `||`/`{}`/`()` 有特殊解析，导致 JS 语法被破坏）→ 用 `write_to_file` 创建临时脚本执行后删除；脚本**必须 `.cjs` 后缀、只用 `require`**（项目 package.json 声明 `type: module` 时 `.js` 会被误判 ESM 报 ERR_REQUIRE_ESM）',
   '>   - 禁止 cmd.exe 语法（如 `for /L %i in (1,1,N) do ...`）→ PowerShell 不支持，改用逐个 `execute_command` 调用或 PowerShell `foreach`',
   '>   - 警告 CLIXML：PowerShell 捕获 `node`/`npx` 子进程输出时可能包装为 `#< CLIXML <Objs...>` 格式 → 检测到 CLIXML 时以文件系统实际产物为准，忽略 stdout',
   '>   - 禁止 `curl`（PowerShell 将 curl 别名为 Invoke-WebRequest）→ HTTP 请求走 `context-client.cjs` / `kb-upload.cjs`，或用 `Invoke-RestMethod`',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.7.8-7",
+  "version": "2.8.0",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
   "main": "lib/init.js",
   "bin": {

package/templates/skills/kld-sdd/opsx-apply/SKILL.md

@@ -338,6 +338,7 @@ g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下
 - **⛔ 渐进式加载 + 隔离红线**：只加载当前 Capability 的四文档链，默认聚焦当前 Capability；为核对已声明依赖可读取相关 Capability 契约并注明来源，不全量加载或混写其他能力。
 - **⛔ DAG 依赖拦截**：执行任务前必须检查依赖，前置未完成必须拦截。
 - **⛔ 编译检查门禁**：每完成一个任务后必须运行编译检查，编译失败禁止标记已完成。
+- **环境型编译失败不算任务失败**：编译报 403/私服认证/依赖下载超时等环境型失败与代码无关，不回滚任务状态、不标记任务失败；失败时记录 `process_note(kind=api_error, target=compile)` 并附真实报错，用户修复环境（如补 settings.xml）且编译门禁重跑通过后记录 `process_note(kind=recovery, target=compile)`；仅重跑编译门禁，任务实现不重做。环境阻塞的任务保持未完成态：不阻断同层独立任务继续；依赖它的任务等待环境修复，不得抢跑；修复后仅重跑受影响任务的编译门禁。
 - **⛔ 测试执行门禁**：根据 `test-strategy` 决定（tdd=强制, impl-first=强制补跑, none=跳过）；须真实执行并留 telemetry。${HOOK_GATE_DESCRIPTION}
 - **⛔ 必须实时更新任务状态**：每完成一个任务立即改 tasks.md，两种格式同步。
 - **⛔ apply 结束前 checkbox 全量同步校验**：`stage_end` 前对比 telemetry `task_update` 记录数与 tasks.md `[x]` 数量，不一致则补齐（见 `./checklist.md` §5f.1）。
@@ -351,13 +352,13 @@ g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下
 - **⛔ 子代理不建分支**：worktree/apply 分支仅在 §1.5（主会话）创建一次，§5 子代理不得再建。
 - **显示进度反馈**：每完成一个任务显示「✅ [TASK-ID] 已完成 [N/M]」。
 - **保持任务聚焦**：每次只处理一个任务。
-- **遇到问题时暂停**：任务描述模糊、编译失败、测试失败或发现设计问题时暂停询问。
+- **遇到问题时暂停**：任务描述模糊、编译失败、测试失败或发现设计问题时暂停询问；其中环境型编译失败（403/私服认证/依赖下载超时）不按代码型失败暂停，按上文「环境型编译失败不算任务失败」处理。
 
 ---
 
 ## 渐进披露
 
-- Read `checklist.md` 仅在执行 apply 需要校验门禁/自检时 — 含 §1.2 Check 门禁检查点、§5d/§5e 编译/测试门禁自检、§5e.1 TDD 节奏校验、§5f.1 checkbox 全量同步校验、§6.0 单元测试真实执行自检、§6.1 worktree 收尾前置条件、Guardrails ⛔ 强制项勾选表。
+- Read `checklist.md` 仅在执行 apply 需要校验门禁/自检时 — 含 §1.2 Check 门禁检查点、§5d/§5e 编译/测试门禁自检、§5e.1 TDD 节奏校验、§5f.1 checkbox 全量同步校验、§5f.2 锚点定位失败降级、§6.0 单元测试真实执行自检、§6.1 worktree 收尾前置条件、Guardrails ⛔ 强制项勾选表。
 - Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板（start/end/task_update/final_output_snapshot/ai_adoption_review/worktree_finish）、§1.5 worktree 全套策略（Step 0.1-3 + record-base + 多 cap 合并顺序）、§5c 子代理派发、§5.1 最终交付文件与 AI 产出快照、§6.0 单元测试、§6.1 worktree 收尾脚本。
 - `implementer-prompt.md` 为子代理派发提示模板（§5c 派发时组合 tasks/design/overview 上下文使用）。
 - `worktree-setup.md` 为 worktree 快速参考（§1.5 策略的精简版，与 reference.md §1.5 完整版并存：reference=完整策略，worktree-setup=快速参考）。

package/templates/skills/kld-sdd/opsx-apply/checklist.md

@@ -30,7 +30,7 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 
 - [ ] 检测项目类型并执行编译命令
 - [ ] 编译成功 → 继续下一步
-- [ ] 编译失败 → **必须立即修复，禁止标记为已完成！**
+- [ ] 编译失败 → **必须立即修复，禁止标记为已完成！**（例外：403/私服认证/依赖下载超时等环境型失败按 SKILL.md「环境型编译失败不算任务失败」处理，记 `process_note(kind=api_error, target=compile)`，不算代码型失败、不暂停修复代码）
 
 ### §5e 测试执行门禁（按 `proposal.md` 的 `test-strategy`）
 
@@ -95,6 +95,14 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 - [ ] 文档更新项（如有）已完成或显式标注推迟
 - [ ] 所有文件就绪后已记录严格 `final_output_snapshot`：`snapshot_kind=final`，`vcs_mode=readonly|no-git`，`files_changed` 等于 `files` 去重数量，新增/删除行数符合 VCS 模式；无交付文件时 `files=[]`、`files_changed=0` 且有具体 `no_output_reason`
 
+### §5f.2 锚点定位失败降级（任务实施中 Edit 失败时）
+
+对 design/tasks 中声明的代码锚点做 Edit 失败时，按序降级；**禁止一次失败即跳过任务、禁止虚构锚点**。任务声明的锚点在目标文件中不存在、或跨文档引用缺失时，同样**禁止静默跳过该任务/步骤**（如跳过 import、跳过调用），按第 3 步暂停上报：
+
+1. **重试**：收窄匹配串（含更多上下文行）或放宽匹配串（去掉行首缩进差异）各重试一次；每次重试记录 `process_note(kind=recovery, target=文件路径)`；
+2. **行块替换**：读取锚点前后 3 行，用该行块作为 `old_str` 重新定位替换；
+3. **暂停上报**：连续 3 次失败后**停止修改**，向用户报告目标文件、锚点声明与已尝试的匹配串，等待用户决策；用户给出处理方式后记录 `process_note(kind=user_decision, decision_type=other, target=文件路径)`。⛔ 禁止用整文件重写方式落地任务产出（重写已有代码文件引入的回归风险远大于锚点失败本身）。
+
 ---
 
 ### §5g 中途 TDD 节奏检查点（每完成 10 个 TDD 任务后强制执行）
@@ -141,7 +149,7 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 - [ ] ⛔ **渐进式加载**：只加载当前 Capability 的四文档链
 - [ ] ⛔ **隔离红线**：默认聚焦当前 Capability；为核对已声明依赖可读取相关 Capability 契约并注明来源，不全量加载或混写其他能力。
 - [ ] ⛔ **DAG 依赖拦截**：执行任务前必须检查依赖，前置未完成必须拦截
-- [ ] ⛔ **编译检查门禁**：每完成一个任务后必须运行编译检查，编译失败禁止标记已完成
+- [ ] ⛔ **编译检查门禁**：每完成一个任务后必须运行编译检查，编译失败禁止标记已完成（环境型失败例外，见 §5d）
 - [ ] ⛔ **测试执行门禁**：根据 `test-strategy` 决定（tdd=强制, impl-first=强制补跑, none=跳过）；须真实执行并留 telemetry，`sdd-apply-test-gate` 校验非占位数据
 - [ ] ⛔ **RED 测试质量门禁**：见 §5e.2（引用 tdd-quality + tdd-anti-patterns，不在此内联复制）
 - [ ] ⛔ **必须实时更新任务状态**：每完成一个任务立即改 tasks.md，两种格式（`- [ ]`→`- [x]` 与 `**状态**: [ ]`→`[x]`）同步
@@ -158,4 +166,5 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 - [ ] **Capability 级并行**：多个 `/opsx-apply` 会话 = 多个 worktree；禁止为未解耦的 cap 仅因 full 模式而拆分支
 - [ ] **显示进度反馈**：每完成一个任务显示「✅ [TASK-ID] 已完成 [N/M]」
 - [ ] **保持任务聚焦**：每次只处理一个任务
-- [ ] **遇到问题时暂停**：任务描述模糊、编译失败、测试失败或发现设计问题时暂停询问
+- [ ] **遇到问题时暂停**：任务描述模糊、编译失败、测试失败或发现设计问题时暂停询问（环境型编译失败除外，见 §5d）
+- [ ] ⛔ **锚点定位失败降级**：见 §5f.2，Edit 失败按重试→行块替换→暂停上报降级，禁止一次失败即跳过任务、禁止整文件重写落地

package/templates/skills/kld-sdd/opsx-apply/reference.md

@@ -147,6 +147,8 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=process_
 | 编辑失败并重试 | `recovery` | 文件 |
 | 用户交互决策点（范围/模式/测试策略） | `user_decision` | - |
 | API 故障 | `api_error` | - |
+| 编译环境失败（403/私服认证/依赖下载超时） | `api_error` | compile |
+| 环境修复后编译门禁重跑通过 | `recovery` | compile |
 | 模型故障 | `model_error` | - |
 | 测试环境异常 | `test_exception` | - |
 

package/templates/skills/kld-sdd/opsx-check/SKILL.md

@@ -50,7 +50,7 @@ node "<spec-package>/skywalk-sdd/log.cjs" semantic-check --project="<spec-packag
 输出 `profile / valid / product_valid / revision / counts`、`product_diagnostics`、`tool_diagnostics`、`review_inputs`、`task_completion` 和 `timings_ms`。程序时间不等于模型评审总耗时。
 
 - `product_valid` 只看产物质量。需求没有验收、需求没有设计、设计没有任务、任务没有上游、验收没有归属需求、产物缺失、任务依赖成环，这些进入报告并阻断 Check。
-- `tool_diagnostics` 是工具升级带来的身份、来源、谱系和归档诊断。预检已把可物化的部分写入 `ontology/spec-ontology.json` 与 `ontology/legacy-mapping.json`，不改 Markdown。不要向用户展示这些诊断，不要要求用户补 UUID、改锚点或重做归档。
+- `tool_diagnostics` 是工具升级带来的身份、来源、版本谱系和归档诊断。预检已把可物化的部分写入 `ontology/spec-ontology.json` 与 `ontology/legacy-mapping.json`，不改 Markdown。不要向用户展示这些诊断，不要要求用户补 UUID、改锚点或重做归档。
 - 交给独立评审者的程序诊断只使用 `product_diagnostics`。报告只写产物缺口和 design 与 tasks 之间的覆盖缺失。
 - semantic-check 已包含全量对账、工作态 JSON 原子刷新和 pending 标记；无需再调用 semantic-reconcile。`product_valid=true` 只表示产物结构没有阻断，不能宣称已完成独立评审或已入库。
 - 默认从产物推断 simple/full；用户或项目明确要求 strict 时传 `--profile=strict`，不能为通过而降级。

package/templates/skills/kld-sdd/opsx-check/reviewer.md

@@ -92,9 +92,29 @@
 - Check 阶段只读，不自动勾选；报告中必须说明这是“任务可能已执行但文档未同步”或“任务真实未完成”的待确认项。
 
 
+## 长文档分批读取
+
+- 单个文件超过 1500 行时必须分段读取（先读前 1500 行，再按需续读缺失部分），避免一次读取撑爆上下文导致输出截断。
+- spec.md / design.md / tasks.md 分多次独立读取，不要把所有文档合并进一次读取；同一文件同一版本只读一次，复用结果。
+
 ## 返回给主 Agent
 
-一次返回 [review-template.json](review-template.json) 的 items、检查范围和必要问题说明；身份由主 Agent 根据真实工具结果补齐。每项包含唯一 id、category、status、evidence。算法归入 consistency，不重复计数；不手算总数，不复述所有通过项，不复制文档全文。
+**⛔ 返回格式硬约束**：最终回复必须包含且仅包含一个 json 代码块，结构与 [review-template.json](review-template.json) 对齐（`reviewer` 身份块由主 Agent 补齐，评审者不写）；JSON 之前的解释文字不得超过 3 行：
+
+```json
+{
+  "items": [
+    { "id": "<唯一ID>", "category": "consistency", "status": "error", "evidence": "spec.md §3.2 要求…但 design.md 未覆盖（文件+章节定位）" }
+  ],
+  "warning_dispositions": []
+}
+```
+
+- `category` ∈ completeness / consistency / executability / tdd_compliance；`status` ∈ passed / error / warning / suggestion / na。
+- 每项必须含 `evidence`（文件+章节定位），na 项写不适用理由；§4.4b 的 DAG 语义警告归入 `warning_dispositions`，不混入 items。
+- 不满足此结构视为 `SUBAGENT_RESULT_INVALID`，主 Agent 会要求补齐一次缺项。
+
+内容要求：items 覆盖全部实际执行的检查；检查范围与必要问题说明写在 JSON 前的 ≤3 行解释文字或对应 item 的 evidence 中，不另起段落；身份块由主 Agent 根据真实工具结果补齐，评审者不写。算法归入 consistency，不重复计数；不手算总数，不复述所有通过项，不复制文档全文。
 
 至少有一个实际适用项。未执行项使用 na 并写原因，不能为计数填“全部通过”。任务状态由工具读取，不能伪造 reviewer 或独立性。主 Agent 无需为统计不匹配重新委派评审。
 

package/templates/skills/kld-sdd/opsx-propose/interaction-policy.md

@@ -8,6 +8,7 @@
 - 用户已要求“完成这个需求”“实现并验证”或连续处理时，在授权范围内加载下一阶段技能并继续，Simple / Full 均适用，不反复索要阶段口令。要求“完善文档”不授权实现代码。
 - 连续推进仍按依赖完成文档、check、apply 和测试；check 未通过不得冒充通过。归档、入库、合并、推送、部署按用户授权分别判断，不能从“实现”推导为已授权发布。
 - 只在业务目标或验收口径存在实质歧义、多个身份无法判定、真实冲突或新增外部副作用需要授权时询问。先读取用户提供的材料与现有代码，集中提出缺失事实，不把 mode、UUID、内部枚举当作业务问题。
+- 同一轮发现多个冲突或待决策项时，合并成一份清单一次问完（含各自选项与建议），不逐个打断用户。
 - 自动选择文档形态和测试策略并简短说明理由；沿用已有变更的设置，不因这次默认规则重排存量目录。
 - 只展示业务差异、必要决策、验证结果和剩余问题。遥测、身份分配、结构化 JSON 由工具和 Agent 维护，不让用户手填，不把自动推断伪记为用户确认。
 
@@ -31,5 +32,6 @@
 
 - 模板用于提示需要考虑的内容，必须保留解析字段、身份、锚点和引用关系；不为填满模板复制教程、空表、重复背景或不适用章节。简单变更直接表达目的、行为、验收、设计决定和可验证任务。
 - 已有全局契约用引用复用；Spec 写行为，Design 只补实现决策，Task 只写交付单元、依赖和验收，不在四份文档重复同一解释。
+- ⛔ 修改已有 SDD 文档禁止整文件覆写（Write 全文重写会冲掉前次修复）；必须用 Edit 定向修改或章节末尾追加。仅用户明确要求重构文档结构时例外。
 - 参数边界可用表驱动验收和测试；只有行为、依赖或交付确实不同才拆任务。若项目明确采用 TDD，保留真实 RED→GREEN 证据与顺序，不机械按每个字段或输入值生成一整套任务。
 - Check 的结构合法性由程序负责，模型聚焦业务覆盖与矛盾；结果按实际检查项输出，由 check-record 计算记账字段。