@tea-agent/loop-agent 0.33.0 → 0.33.2

package/dist/worker/observe/static/styles.css

@@ -76,59 +76,6 @@ body {
 	line-height: 1.5;
 }
 
-.embedded-operator-nav {
-	display: none;
-}
-
-body[data-embedded-shell="true"] .site-header .logo {
-	display: none;
-}
-
-body[data-embedded-shell="true"] .site-header {
-	position: sticky;
-	top: 49px;
-	z-index: 30;
-	grid-template-columns: 1fr auto;
-	grid-template-areas: "nav status" "crumb crumb";
-	min-height: 56px;
-	margin-bottom: var(--space-5);
-	padding: 10px 0;
-}
-
-body[data-embedded-shell="true"] .embedded-operator-nav {
-	position: sticky;
-	top: 0;
-	z-index: 40;
-	display: flex;
-	gap: 6px;
-	align-items: center;
-	padding: 8px max(24px, calc((100vw - 1680px) / 2));
-	border-bottom: 1px solid var(--hairline);
-	background: color-mix(in srgb, var(--canvas) 92%, transparent);
-	backdrop-filter: blur(10px);
-	font-size: 13px;
-	font-weight: 700;
-}
-
-.embedded-operator-nav a,
-.embedded-operator-nav span {
-	padding: 6px 12px;
-	border-radius: var(--radius-pill);
-	text-decoration: none;
-}
-
-.embedded-operator-nav a:hover,
-.embedded-operator-nav a:focus-visible {
-	background: var(--surface);
-	color: var(--orange-active);
-	outline: none;
-}
-
-.embedded-operator-nav span {
-	background: var(--ink);
-	color: #fff;
-}
-
 button,
 input,
 select,
@@ -149,7 +96,6 @@ pre,
 .dag-node-table td:nth-child(2),
 td:first-child,
 .meta-item dd,
-.header-refresh,
 .kpi-value,
 .risk-total,
 .process-timeline-time {
@@ -176,140 +122,13 @@ td:first-child,
 #app {
 	width: min(100% - 48px, 1680px);
 	margin: 0 auto;
-	padding-bottom: 56px;
-}
-
-.site-header {
-	position: sticky;
-	top: 0;
-	z-index: 30;
-	display: grid;
-	grid-template-columns: auto 1fr auto;
-	grid-template-areas: "brand nav status" "crumb crumb crumb";
-	column-gap: var(--space-5);
-	align-items: center;
-	min-height: 72px;
-	margin-bottom: var(--space-6);
-	padding: 14px 0 12px;
-	background: color-mix(in srgb, var(--canvas) 82%, transparent);
-	border-bottom: 1px solid var(--hairline);
-	backdrop-filter: blur(12px);
-}
-
-.logo {
-	grid-area: brand;
-	display: inline-flex;
-	align-items: center;
-	gap: 10px;
-	color: var(--ink);
-	font-size: 15px;
-	font-weight: 650;
-	letter-spacing: -0.01em;
-	text-decoration: none;
-}
-
-.logo > i {
-	display: inline-flex;
-	align-items: center;
-	justify-content: center;
-	width: 32px;
-	height: 32px;
-	border-radius: var(--radius-md);
-	background: var(--orange-soft);
-	color: var(--orange-active);
-	font-size: 18px;
-	font-weight: 400;
-}
-
-.logo:hover {
-	color: var(--orange-active);
-}
-
-.top-nav {
-	grid-area: nav;
-	display: inline-flex;
-	flex-wrap: wrap;
-	align-items: center;
-	gap: 4px;
-	justify-self: start;
-	padding: 5px;
-	border: 1px solid var(--hairline);
-	border-radius: var(--radius-pill);
-	background: color-mix(in srgb, var(--surface) 88%, transparent);
-	box-shadow: var(--shadow-panel);
-}
-
-.nav-link {
-	display: inline-flex;
-	align-items: center;
-	gap: 7px;
-	min-height: 34px;
-	padding: 0 14px;
-	border: 1px solid transparent;
-	border-radius: var(--radius-pill);
-	color: var(--body);
-	font-size: 13px;
-	font-weight: 600;
-	text-decoration: none;
-	transition:
-		border-color var(--transition-fast),
-		background-color var(--transition-fast),
-		color var(--transition-fast),
-		box-shadow var(--transition-fast);
-}
-
-.nav-link > i {
-	font-size: 15px;
-	font-weight: 400;
-}
-
-.nav-link:hover,
-.nav-link:focus-visible {
-	border-color: transparent;
-	background: var(--surface);
-	color: var(--ink);
-	outline: none;
-}
-
-.nav-link-active {
-	border-color: transparent;
-	background: var(--ink);
-	color: #fff;
-	box-shadow: none;
-}
-
-.nav-link-active:hover,
-.nav-link-active:focus-visible {
-	background: var(--ink);
-	color: #fff;
-}
-
-.header-meta {
-	grid-area: status;
-	display: inline-flex;
-	justify-self: end;
-	align-items: center;
-	gap: 8px;
-	min-height: 34px;
-	padding: 0 12px;
-	border: 1px solid var(--hairline);
-	border-radius: var(--radius-pill);
-	background: var(--surface);
-	color: var(--muted);
-	font-size: 12px;
-	font-variant-numeric: tabular-nums;
-	box-shadow: var(--shadow-panel);
-}
-
-.header-meta > i {
-	color: color-mix(in srgb, var(--green) 70%, white);
-	font-size: 14px;
+	padding: var(--space-5) 0 56px;
 }
 
 .breadcrumb {
-	grid-area: crumb;
 	display: flex;
 	min-height: 16px;
+	margin-bottom: var(--space-4);
 	gap: 7px;
 	color: var(--muted);
 	font-size: 12px;
@@ -344,6 +163,65 @@ td:first-child,
 	gap: var(--space-4);
 }
 
+/* 「昨夜班次」条带：夜间结果在观测总览的唯一一级呈现（管理动作在操作侧） */
+.night-strip {
+	display: flex;
+	align-items: center;
+	gap: 14px;
+	padding: 13px 18px;
+	margin-bottom: var(--space-4);
+	border-left: 3px solid var(--lavender);
+	background: linear-gradient(
+		90deg,
+		color-mix(in srgb, var(--lavender) 22%, var(--surface)),
+		var(--surface) 55%
+	);
+}
+.night-strip[hidden] {
+	display: none;
+}
+.night-strip-icon {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	flex: 0 0 auto;
+	width: 34px;
+	height: 34px;
+	border-radius: 10px;
+	background: color-mix(in srgb, var(--lavender) 55%, var(--surface));
+	color: #6a4a9e;
+	font-size: 16px;
+}
+.night-strip-main {
+	min-width: 0;
+}
+.night-strip-title {
+	font-size: 13px;
+	font-weight: 700;
+	color: var(--ink);
+}
+.night-strip-sub {
+	margin-top: 1px;
+	font-size: 12px;
+	color: var(--body);
+	font-variant-numeric: tabular-nums;
+}
+.night-strip-actions {
+	margin-left: auto;
+	display: inline-flex;
+	align-items: center;
+	gap: 8px;
+	flex-shrink: 0;
+}
+.night-strip-manage {
+	border-color: color-mix(in srgb, var(--orange) 35%, var(--hairline));
+	color: var(--orange-active);
+}
+.night-strip-manage:hover {
+	border-color: var(--orange);
+	background: var(--orange-soft);
+}
+
 .view-heading {
 	display: grid;
 	gap: 4px;
@@ -638,75 +516,6 @@ td:first-child,
 	gap: var(--space-3);
 }
 
-.repo-banner {
-	display: flex;
-	align-items: flex-start;
-	gap: 10px;
-	padding: 6px 12px;
-	border: 1px solid var(--hairline);
-	border-radius: var(--radius-md);
-	background: transparent;
-}
-.repo-banner-inline {
-	justify-self: end;
-	align-items: center;
-	max-width: min(48ch, 100%);
-	padding: 4px 10px 4px 8px;
-	border: 1px solid var(--hairline);
-	border-radius: 999px;
-	background: var(--canvas-soft);
-}
-.repo-banner-icon {
-	display: inline-flex;
-	align-items: center;
-	justify-content: center;
-	flex: 0 0 auto;
-	width: 28px;
-	height: 28px;
-	border-radius: 8px;
-	background: var(--surface);
-	border: 1px solid var(--hairline);
-	color: var(--orange-active);
-}
-.repo-banner-icon > i {
-	font-size: 15px;
-	line-height: 1;
-}
-.repo-banner-inline .repo-banner-text {
-	display: grid;
-	justify-items: start;
-	gap: 1px;
-	min-width: 0;
-}
-.repo-banner-text {
-	display: flex;
-	flex-wrap: wrap;
-	align-items: baseline;
-	gap: 6px 10px;
-	min-width: 0;
-}
-.repo-banner-name {
-	color: var(--ink);
-	font-size: 13px;
-	font-weight: 700;
-	letter-spacing: 0.01em;
-	line-height: 1.25;
-	overflow: hidden;
-	text-overflow: ellipsis;
-	white-space: nowrap;
-}
-.repo-banner-path {
-	color: var(--muted);
-	font-size: 11px;
-	line-height: 1.35;
-	font-variant-numeric: tabular-nums;
-	letter-spacing: 0.01em;
-	overflow: hidden;
-	text-overflow: ellipsis;
-	white-space: nowrap;
-	max-width: 36ch;
-}
-
 .panel-kpi {
 	display: grid;
 	grid-template-columns: var(--dashboard-cols);
@@ -1315,7 +1124,7 @@ tr.clickable:focus-within {
 .dag-inspector {
 	position: fixed;
 	z-index: 40;
-	/* Align with site-header top edge; same inset as right/bottom. */
+	/* Align near the unified chrome bottom edge; same inset as right/bottom. */
 	top: 24px;
 	right: 24px;
 	bottom: 24px;
@@ -2845,11 +2654,6 @@ body.is-resizing-dag-graph {
 	#app {
 		width: min(100% - 32px, 1680px);
 	}
-	.site-header {
-		grid-template-columns: auto 1fr auto;
-		grid-template-areas: "brand nav status" "crumb crumb crumb";
-		row-gap: 8px;
-	}
 	.run-detail-workspace {
 		grid-template-columns: 1fr;
 	}
@@ -2864,14 +2668,6 @@ body.is-resizing-dag-graph {
 	.dashboard-page-header {
 		grid-template-columns: 1fr;
 	}
-	.repo-banner-inline {
-		justify-self: start;
-		max-width: none;
-	}
-	.repo-banner-path {
-		max-width: none;
-		white-space: normal;
-	}
 	.pool-toolbar {
 		justify-items: start;
 	}
@@ -2888,9 +2684,6 @@ body.is-resizing-dag-graph {
 	#app {
 		width: min(100% - 24px, 1680px);
 	}
-	.site-header {
-		margin-bottom: var(--space-6);
-	}
 	.kpi-grid {
 		grid-template-columns: repeat(2, minmax(0, 1fr));
 	}

package/dist/worker/observe/static/views/dashboard.js

@@ -16,7 +16,7 @@ import {
 	DAG_EFFECTIVE_STATUS_LABELS,
 	STATUS_LABELS,
 } from "../constants.js";
-import { el, reconcileKeyed, syncCompatibleNode } from "../dom.js";
+import { clearNode, el, reconcileKeyed, syncCompatibleNode } from "../dom.js";
 import {
 	badge,
 	badgeClass,
@@ -65,7 +65,7 @@ import {
 } from "../dag-model.js";
 import { layoutDag } from "../dag-layout.js";
 import { showView, setBreadcrumb, updateHeaderRefresh } from "../shell-chrome.js";
-	import { kpiCard, renderRepoBanner, renderProjectionFault, failuresInboxLink } from "../kpi.js";
+	import { kpiCard, renderProjectionFault, failuresInboxLink } from "../kpi.js";
 	import {
 		dagSortTime,
 		compareActiveDagUrgency,
@@ -82,6 +82,55 @@ let kpiDagGroup = null;
 // removed once on first success so subsequent polls never see it again.
 let dashboardLoadingNode = null;
 
+/**
+ * 「昨夜班次」条带：夜间结果在观测侧的唯一一级呈现（替代旧「夜间任务」tab）。
+ * 管理动作（晨审处置）始终落在操作侧 /#/night，保持 Inspect 只读不变式。
+ */
+async function renderNightStrip() {
+	const strip = document.getElementById("dashboard-night");
+	if (!strip) return;
+	const morning = await fetchJson("/api/night-jobs/morning");
+	const summary = morning?.summary ?? null;
+	if (!morning || !summary || !(summary.total > 0)) {
+		strip.hidden = true;
+		clearNode(strip);
+		return;
+	}
+	clearNode(strip);
+	strip.hidden = false;
+
+	const iconWrap = el("span", "night-strip-icon");
+	const moon = el("i", "ri-moon-clear-line");
+	moon.setAttribute("aria-hidden", "true");
+	iconWrap.appendChild(moon);
+	strip.appendChild(iconWrap);
+
+	const main = el("div", "night-strip-main");
+	main.appendChild(el("div", "night-strip-title", `昨夜班次 · ${morning.date ?? ""}`));
+	const parts = [
+		`${summary.succeeded ?? 0} 通过`,
+		`${summary.failed ?? 0} 失败`,
+	];
+	if (summary.humanRequired > 0) parts.push(`${summary.humanRequired} 需人工`);
+	if (summary.pendingHarvest > 0) parts.push(`${summary.pendingHarvest} 待 harvest`);
+	main.appendChild(el("div", "night-strip-sub", parts.join(" · ")));
+	strip.appendChild(main);
+
+	const actions = el("div", "night-strip-actions");
+	const detail = el("a", "page-action-btn", "夜间详情");
+	detail.href = "#/night";
+	detail.addEventListener("click", (e) => {
+		e.preventDefault();
+		navigate("/night");
+	});
+	actions.appendChild(detail);
+	const manage = el("a", "page-action-btn night-strip-manage", "晨审处置 →");
+	manage.href = "/#/night";
+	manage.title = "夜间计划的管理与晨审处置在操作台完成（Inspect 保持只读）";
+	actions.appendChild(manage);
+	strip.appendChild(actions);
+}
+
 export async function renderDashboard(scrollTo) {
 	showView("dashboard");
 	setBreadcrumb([{ label: UI_TEXT.dashboard }]);
@@ -92,7 +141,6 @@ export async function renderDashboard(scrollTo) {
 	const riskEl = document.getElementById("dashboard-risk");
 	const dagsEl = document.getElementById("dashboard-dags");
 	const batchesEl = document.getElementById("dashboard-batches");
-	const repoEl = document.getElementById("dashboard-repo");
 	const host = kpiEl || featureEl || activeEl;
 	// Loading only mounts before the first successful snapshot. Subsequent
 	// successful polls reuse the stable DOM and never flash the loading state.
@@ -211,7 +259,7 @@ export async function renderDashboard(scrollTo) {
 		},
 	);
 
-	renderRepoBanner(repoEl, snapshot);
+	renderNightStrip();
 
 	const dagHealth = snapshot.health?.dag;
 	const dagActiveRuns = dagHealth?.activeRuns ?? activeDags.length;

package/dist/workflows/dag/retry-policy.js

@@ -19,6 +19,8 @@ export const DEFAULT_DAG_RETRY_CATEGORIES = [
 ];
 export const STRUCTURED_OUTPUT_RETRY_CATEGORY = "output-too-large";
 export const PROTOCOL_INVALID_RETRY_CATEGORY = "protocol-invalid";
+/** Recoverable model artifact/schema formatting failure on read-only structured nodes. */
+export const STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY = "invalid-output";
 /** Retry only a proven no-op from an explicitly opt-in bounded Pi writer. */
 export const WRITER_EMPTY_DIFF_RETRY_CATEGORY = "writer-empty-diff";
 /** Retry when a backend-test writer finished but Completeness Gate found missing/broken targets. */
@@ -26,16 +28,19 @@ export const INCOMPLETE_WRITE_SET_RETRY_CATEGORY = "incomplete-write-set";
 export const STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES = [
     ...DEFAULT_DAG_RETRY_CATEGORIES,
     STRUCTURED_OUTPUT_RETRY_CATEGORY,
+    STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
 ];
 /** Categories allowed on nodes that declare a machine-readable outputProtocol. */
 export const PROTOCOL_AWARE_DAG_RETRY_CATEGORIES = [
     ...DEFAULT_DAG_RETRY_CATEGORIES,
     PROTOCOL_INVALID_RETRY_CATEGORY,
+    STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
 ];
 export const ALL_DAG_RETRY_CATEGORIES = [
     ...DEFAULT_DAG_RETRY_CATEGORIES,
     STRUCTURED_OUTPUT_RETRY_CATEGORY,
     PROTOCOL_INVALID_RETRY_CATEGORY,
+    STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
     WRITER_EMPTY_DIFF_RETRY_CATEGORY,
     INCOMPLETE_WRITE_SET_RETRY_CATEGORY,
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.33.0",
+  "version": "0.33.2",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/analyze-product-dependencies/SKILL.md

@@ -1,67 +1,108 @@
 ---
 name: analyze-product-dependencies
-description: 基于 complete Product Requirement 探索代码库，按 frontend、backend 或 both 范围将故事、输出规范和验收标准映射到真实文件、组件、服务、数据、权限与证据，并仅为 API 型后端故事生成精简 Swagger 风格 Markdown API 文档。用于代码影响分析、依赖分析、API 文档或需求到代码映射。
+description: 面向采用 Product Requirement V4、Web/Remote 接口分类和统一 HTTP 200 响应包络的组织内部项目，先根据选中需求故事强制检索项目知识库，再探索代码库，按 frontend、backend 或 both 范围将故事、验收标准及 API 型后端故事映射到真实文件、路由、组件、服务、数据、权限与证据；API 场景从同一规范中间模型生成纯 HTTP 契约文档，或用 api-only 模式单独更新 API 文档。用于代码影响分析、依赖分析、API 文档或需求到代码映射；也适用于“这个需求要改哪些文件”“帮我生成接口文档”“需求对应到哪段代码”“评估下这个需求的开发影响”这类请求。
 ---
 
 # Analyze Product Dependencies
 
 IRON LAW：`product-requirement.md` 是唯一需求事实源。不得从原始需求、Product Analysis、Clarification 或聊天重新解释需求，不得修改代码或上游产物。
 
+## 运行环境与外部能力
+
+- 必需：可读写当前项目文件，并能运行 Node.js `.mjs` 校验器。
+- 前置第三方 skill：`kb-design-assist`，用于根据选中需求故事检索项目知识库中的设计系统、业务规范、API 规范和其他项目约定。
+- 可选能力：隔离的只读代码侦察 agent。
+- 缺少隔离代码侦察 agent 时执行对应 fallback；`kb-design-assist` 为 `unavailable` 时必须先让用户选择“修复后重试”或“跳过知识库”，不得直接 fallback，也不得伪造知识库结果、代码证据或 agent 结果。
+- 调用第三方 skill 时使用当前宿主提供的原生 skill 加载机制，不假定具体命令或工具名称。
+
 ## 输入与产物
 
-- 必填：complete `product-requirement.md` 的实际路径和可读取代码仓库路径；Product Requirement 必须位于项目根的需求目录。
+- 必填：complete `product-requirement.md` 的实际路径和可读取代码仓库路径。Product Requirement 必须位于 `<project-root>/docs/product-analysis/<requirement-id>/`。
 - 可选：`target=frontend|backend|both` 或 `--target frontend|backend|both`；两种写法等价，默认继承上游 scope。
-- 输出写回 Product Requirement 所在目录；始终生成 `dependency-analysis.md`，选中 API 型后端故事时额外生成 `api-documentation.md`。
+- 可选：`mode=full|api-only` 或 `--mode full|api-only`；两种写法等价，默认 `full`。`full` 生成依赖分析并按需生成 API 文档；`api-only` 只生成 `api-documentation.md`，不创建或修改 `dependency-analysis.md`。
+- 可选：frontend/both 可传 `api_documentation=<任意可读 Markdown API 文档路径>` 或 `--api-doc <path>`。外部文档只读，前端产物只记录实际引用的 Method+Path。
+- 输出写回 Product Requirement 所在目录。`api-only` 仅适用于 `backend|both` 且至少一个选中后端故事以 API 触发。用户显式要求刷新依赖/API 产物时，视为授权原子更新本 skill 在本次运行创建的文件；覆盖既有 complete 产物、非本 skill 创建的文件或来源无法确认的文件前先确认。
 
 ## Workflow
 
 - [ ] Step 0：输入门禁 ⛔ BLOCKING
-  - [ ] 读取 `references/input-contract.md` 并运行 Product Requirement 输入校验器。
-  - [ ] 将 `target=<value>` 和 `--target <value>` 归一化为唯一 target；缺省时继承上游 scope，非法值或冲突的多个值必须停止。
-  - [ ] 从 Product Requirement 继承 `requirement_id`、`project_root` 和输出目录；显式 target 必须是上游 scope 的子集，只校验和分析选中故事。
+  - [ ] 将 `target=<value>` 和 `--target <value>` 归一化为唯一 target；缺省时继承上游 scope，非法值或冲突的多个值必须停止。显式 target 必须是上游 `analysis_scope` 的子集，只分析选中故事，不改写上游产物。
+  - [ ] 将 `mode=<value>` 和 `--mode <value>` 归一化为唯一 mode；缺省时为 `full`，非法值或冲突值必须停止。`api-only + frontend` 或没有 API 型后端故事时必须停止，不得生成空 API 文档。
+  - [ ] 读取 `references/input-contract.md`，向输入校验器传入已归一化 target。输入必须是上游交付的 complete 产物（不得依赖 `--allow-pending`）；V2 + API 触发故事必须先升级为 V4。
+  - [ ] 从 Product Requirement 继承 `requirement_id` 和输出目录；项目根由固定目录结构推导。`requirement-missing` 且无法从用户显式 `requirement_id`/输出路径恢复时：`full` 不写产物，只在会话报告；能恢复 ID 时才写 blocked Dependency。
   - [ ] 在代码侦察前明确回显“分析范围：frontend | backend | both”；新增产物的 `analysis_scope` 必须等于该归一化 target，后续不得自动扩大范围。
-  - [ ] 门禁失败时只生成 blocked Dependency Analysis，不伪造 API 或代码落点。
+  - [ ] `full` 门禁失败且可确定输出位置时只生成 blocked Dependency Analysis，不伪造 API 或代码落点；`api-only` 门禁失败时不写任何产物，只报告阻断原因和恢复条件。
 - [ ] Step 1：完整代码侦察 ⚠️ REQUIRED
-  - [ ] 读取 `references/scouting-rules.md`。
-  - [ ] 逐个读取选中故事及其同 ID 输出规范和 AC，再定位入口、调用链、状态、类型、数据、权限、错误、日志和测试；`frontend` 不分析 `BE-US-*`，`backend` 不分析 `FE-US-*`。
-  - [ ] 区分 confirmed、inferred、unknown，并为每项结论提供证据。
+  - [ ] 从选中故事、同 ID 输出规范和 AC 提取业务词、领域对象、状态/边界、权限、接口形态与技术约定，形成仅覆盖当前分析范围的知识库检索计划；不得先探索代码库再反推检索词。
+  - [ ] 首先读取 `references/kb-integration.md` 和 `references/scouting-rules.md`，并按前者的状态机、用户确认门禁和降级边界真实调用 `kb-design-assist`。每次分析都必须执行，不得因故事简单或未显式提到项目规范而跳过。
+  - [ ] 知识库状态为 `executed-hit` 或 `executed-no-match`，或 `unavailable` 后用户明确确认跳过，才允许预扫描项目资料并探索代码库；其余情况保持阻断。
+  - [ ] 知识库门禁通过后、常规代码侦察前，依次预扫描 `<project-root>/ai_workspace/project-how-to`、`code-specification`、`project-business`：先枚举文件，再读取入口文档及与选中故事直接相关的内容；缺失目录记录 `not-found` 并继续。
+  - [ ] 按 scouting rules 的只读代码侦察 agent 委派、confirmed/inferred/unknown 分级、双证据要求与前后端必查项执行；当前宿主不支持隔离 agent 时由当前 agent 执行同等范围的定向搜索。当前会话只保留精简规范证据、代码证据、冲突和未定位项。知识库证据不得替代真实代码落点。
+  - [ ] `full` 逐个读取选中故事及其同 ID 输出规范和 AC，再定位入口、调用链、状态、类型、数据、权限、错误、日志和测试；`frontend` 不分析 `BE-US-*`，`backend` 不分析 `FE-US-*`。`api-only` 只侦察生成 HTTP 契约所需的路由惯例、共享 DTO/Schema、统一响应/错误、分页、时间与标识符规范，不做影响文件清单和非 API 依赖分析。
+  - [ ] unknown 不在本 skill 内发起产品澄清：目标行为已明确但代码落点/复用点未知时记入对应故事风险或跨故事未定位项；缺失 API 业务语义、权限、核心规则、安全边界或验收所需产品决策时阻断并返回上游需求 skill，不得自行补齐。
 - [ ] Step 2：判断 API 适用性 ⚠️ REQUIRED
-  - [ ] 只要一个选中的 `BE-US-*` 触发方式为 API，就必须生成 API 文档。
-  - [ ] target 为 `frontend` 时不读取或分析后端故事，不生成 API 文档或 API 实现映射。
+  - [ ] 只要一个选中的 `BE-US-*` 触发方式为 `API（Web）`、`API（Remote）` 或 `API（Web + Remote）`，就必须生成 API 文档。Web 与 Remote 使用同一 HTTP 契约；Web + Remote 必须建模为两个独立接口，路径以知识库、项目资料与仓库规范为准。
+  - [ ] 笼统的 `触发方式：API` 视为接口范围未确认，阻断并返回上游需求 skill。
+  - [ ] target 为 `frontend` 时不读取或分析后端故事，也不新生成 API 文档；Dependency 仍保留 API 实现映射章节。传入外部 API 文档时，只登记被选中前端故事实际依赖且可在文档中核验的 Method+Path，不记录 API ID、Operation ID、文档路径或完整契约；外部文档中的无关接口不参与孤立检查。未传入或未定位时写带原因的不适用。
   - [ ] 定时任务、事件、消息、数据迁移或纯内部调用且不形成 HTTP 契约时，不生成空 API 文档。
-  - [ ] 无 API 时 Dependency Analysis 使用 `source_api_documentation: none`，API 实现映射明确写不适用。
-- [ ] Step 3：建立 Canonical API Model ⚠️ REQUIRED
-  - [ ] API 场景读取 `references/api-documentation-schema.md`。
-  - [ ] 结合 Product Requirement 的业务契约与仓库现有 API 规范，确定方法、路径、参数、响应、错误、Schema、分页、示例和代码落点。API 文档不输出认证方式或权限要求。
-  - [ ] 定义接口字段前，先搜索共享 DTO/Schema、OpenAPI components、统一响应和分页模型；命中时直接复用，不重复定义，不在 API 文档中输出搜索过程或“复用检查”。
-  - [ ] 定义返回 code 前，先搜索全局错误枚举、code 映射和错误响应外壳；命中时直接复用，仅未命中时才定义局部 code，不在 API 文档中输出搜索过程或“复用检查”。
-  - [ ] 分页接口将每页条数参数定义为可选，可选值必须完整包含 `10`、`20`、`50`、`100`；默认值仅在 Product Requirement 或仓库通用分页定义明确时写入。
+  - [ ] 无 API 时 API 实现映射明确写不适用。
+- [ ] Step 3：建立规范 API 中间模型（仅 API 场景）⚠️ REQUIRED when applicable
+  - [ ] 仅当选中范围内存在 API 型后端故事，或 `mode=api-only` 时执行本步；`frontend`、非 API 场景或已判定不适用时跳过，不建立中间模型。
+  - [ ] 读取 `references/api-documentation-schema.md`，按契约建模与渲染。
+  - [ ] 用同一次代码侦察建立不落盘的规范中间模型（最小字段：API ID、Operation ID、Method+Path、变更类型、请求/响应字段、错误码、分页是否适用）；`full` 的 API Documentation 与 Dependency Analysis 的 API 映射均从该模型渲染；`api-only` 只渲染 API Documentation。
+  - [ ] 所有成功与失败响应的 HTTP 状态码统一为 `200`，只通过响应体顶层 `code` 区分结果；成功与失败 `code` 必须不同。定义字段/错误码前，先通过 `kb-design-assist` 检索当前有效的 DTO/Response、统一响应和错误码规范，再核验仓库共享 DTO、响应类型和全局错误枚举；命中则复用，不在 API 文档输出搜索过程、知识库证据或“复用检查”。
+  - [ ] 分页允许值以 Product Requirement 为准；上游确实未说明时按“有效知识库分页规范 > 仓库通用分页定义 > 默认集合 `10`、`20`、`50`、`100`”补齐。参数必填性与默认值沿用 Product Requirement；PR 未规定时优先采用有效知识库规范并由仓库定义核验。
   - [ ] 产品需求优先于现状；业务语义缺失时阻断，不由本 skill 发明产品决策。
-  - [ ] API 文档只保留 HTTP 契约、字段、响应、错误与分页参数；完全移除认证方式、权限要求、业务规则、处理流程、分支逻辑、数据读写逻辑和实现算法及其相关内容。
-  - [ ] API 文档与依赖分析必须从同一模型渲染。
+  - [ ] API 文档只保留 HTTP 契约；不得包含故事/AC 追溯、认证、权限、业务规则与实现逻辑。只有实际分页时才生成“分页约定”。
 - [ ] Step 4：生成产物 ⚠️ REQUIRED
-  - [ ] 读取 `references/dependency-analysis-schema.md`。
-  - [ ] API 场景先写 Swagger 风格 Markdown `api-documentation.md`，再写 `dependency-analysis.md`。
-  - [ ] `frontend` 产物只包含前端故事覆盖和前端依赖详情；`backend` 只包含后端故事覆盖、后端依赖详情和适用的 API 映射；`both` 才包含两端。
-  - [ ] `影响文件` 是每个故事的完整权威文件清单，使用 `F1`、`F2` 编号和 add/modify/reuse；其他落点字段引用这些编号，不重复完整路径。
-  - [ ] Dependency 的 API 实现映射只保留 API ID、Operation ID、方法路径和代码入口，不复制故事、AC 或完整接口文档。
-  - [ ] 所有新增产物与 Product Requirement 使用相同 `requirement_id`，同目录引用使用 `./文件名`。
+  - [ ] `full` 读取 `references/dependency-analysis-schema.md`；`api-only` 不读取或生成 Dependency Analysis。
+  - [ ] `full` 的 API 场景先写 `api-documentation.md`，再写 `dependency-analysis.md`；`api-only` 只写 `api-documentation.md`，不得创建、覆盖或追加 `dependency-analysis.md`。
+  - [ ] 按 target 生成对应故事覆盖与依赖详情；三种范围都保留 API 实现映射章节。
+  - [ ] `影响文件` 是每个故事独立完整的权威清单（故事内 `F1`/`F2` + `add|modify|reuse` 或中文同义 `新增|修改|复用`）；不得建立全局文件索引。
+  - [ ] 前端详情必须覆盖 Product Requirement 的目标页面路由。传入外部 API 文档且依赖 HTTP 时只写 Method+Path；否则按 schema 写“`不适用；…`”模板。
+  - [ ] 故事局部风险与文末跨故事风险不得重复；API 实现映射只保留 API ID、Operation ID、方法路径和代码入口（现有路径或拟新增路径，禁止「未定位」占位）。
+  - [ ] 所有新增产物与 Product Requirement 使用相同 `requirement_id`；V4 frontmatter 不记录可由目录或运行参数推导的来源路径。
 - [ ] Step 5：验证并交付 ⛔ BLOCKING
   - [ ] Product Requirement 输入校验必须通过。
-  - [ ] 向 Product Requirement、Dependency 和适用的 API 校验器传入归一化 target；API 场景运行 API 和 Dependency 两个校验器，非 API 场景只运行 Dependency 校验器。
-  - [ ] 覆盖矩阵承担全局追溯，不生成重复的文末追溯汇总。
-  - [ ] 运行 validator matrix，修复全部错误后再声明完成。
+  - [ ] 向所有适用校验器传入归一化 target。`full` 的 API 场景运行输入、API 和 Dependency 三个校验器；非 API 场景运行输入和 Dependency；`api-only` 只运行输入和 API。
+  - [ ] 当前产物校验通过即可交付。`test-validators.mjs` 仅在修改输出契约、schema、validator、artifact version、示例、forward-test contract，或发布/安装/回归验证时运行。
+
+完整示例按需读取 `references/example.md`；维护或 forward-test 时读取 `references/forward-test-cases.md`。不要为了执行校验而阅读脚本，直接运行。
+
+## Anti-Patterns
 
-完整示例按需读取 `references/example.md`；维护或 forward-test 时读取 `references/forward-test-cases.md`。
+- 从聊天、Product Analysis 或 Clarification 重新解释需求。
+- 修改代码或上游 `product-requirement.md`。
+- 消费带 `--allow-pending` 的未交付产物，或对 V2 + API 故事直接生成 API 文档。
+- 在 API 文档写入故事/AC、认证、权限、业务规则或“复用检查”。
+- 在 API 文档写入 `kb-design-assist` 调用过程、`KB-EVIDENCE-*`、知识库路径、命中日志或规范复用证据。
+- Product Requirement 已给出分页允许值时，用知识库规范、默认 `10/20/50/100` 或仓库惯例覆盖。
+- 建立全局文件索引，或把完整 API 契约/JSON 示例复制进 Dependency Analysis。
+- `api-only` 模式下创建或修改 `dependency-analysis.md`。
+- 自行补齐缺失的产品决策而不返回上游需求 skill。
+- `kb-design-assist` 为 `unavailable` 时，未让用户选择修复或跳过就继续代码库降级或生成 complete 产物。
+- 跳过需求驱动的知识库检索、先探索代码库，或用“故事不涉及项目规范”记录未执行状态。
+
+## 交付前自检
+
+声明完成前逐项确认，任一不满足不得交付：
+
+- [ ] 新增 V4 产物与 Product Requirement 同目录、同 `requirement_id`，且 frontmatter 不含可推导的来源、项目根或仓库路径。
+- [ ] 所有产物 `analysis_scope` 等于归一化 target，未自动扩大范围。
+- [ ] 按场景运行对应校验器：`full` API 场景跑「输入 + API + Dependency」，`full` 非 API 场景跑「输入 + Dependency」，`api-only` 只跑「输入 + API」。
+- [ ] 所有适用校验命令返回 exit 0；任一非 0 都不算完成。
 
 ## Validation
 
+把 `<skill-root>` 解析为本 `SKILL.md` 所在目录，全部参数使用绝对路径：
+
 ```bash
 node <skill-root>/scripts/validate-product-requirement-input.mjs <product-requirement.md> --target <frontend|backend|both>
 node <skill-root>/scripts/validate-api-documentation.mjs <product-requirement.md> <api-documentation.md> --target <backend|both>
-node <skill-root>/scripts/validate-dependency-analysis.mjs <product-requirement.md> <dependency-analysis.md> [api-documentation.md] --target <frontend|backend|both>
-node <skill-root>/scripts/test-validators.mjs
+node <skill-root>/scripts/validate-dependency-analysis.mjs <product-requirement.md> <dependency-analysis.md> [api-documentation.md] [--api-doc <external-api.md>] --target <frontend|backend|both>
 ```
 
+`api-only` 只运行前两条适用命令；不得调用 Dependency 校验器。
 非 API 场景省略 API 校验器和 Dependency 校验命令的第三个参数。
 缺少 Product Requirement 的 blocked 场景使用 `none` 作为 Dependency 校验命令的第一个参数。
+维护或发布时额外运行 `node <skill-root>/scripts/test-validators.mjs`。