@tea-agent/loop-agent 0.33.0 → 0.33.2

package/skills/analyze-product-dependencies/references/api-documentation-schema.md

@@ -1,30 +1,35 @@
-# Swagger 风格 Markdown API 文档 V3 契约
+# Swagger 风格 Markdown API 文档 V4 契约
 
 文件名固定为 `api-documentation.md`。它采用 Swagger 的信息组织方式，但不是 OpenAPI YAML。
 
 ```yaml
 ---
-artifact_version: "3.0"
+artifact_version: "4.0"
 artifact_type: api-documentation
 requirement_id: <与 Product Requirement 一致>
-project_root: ../../..
 api_status: complete
 analysis_scope: backend | both
-source_product_requirement: ./product-requirement.md
-repository_root: ../../..
 ---
 ```
 
-固定章节：通用约定、API 索引、API 详情、数据模型、错误码。API 索引同时承担目录和故事/AC 追溯，不生成重复汇总。API 文档中完全移除认证方式、权限要求、业务规则、业务逻辑、处理逻辑和实现逻辑及其相关内容。
+Frontmatter 只允许以上五个字段，不得增加来源、项目根、仓库路径或其他运行时字段。
 
-通用约定包含 Base URL、统一响应结构、错误响应结构、分页约定、时间和标识符规范。不输出公共定义的搜索过程、命中证据或“复用检查”章节。
+固定章节：通用约定、API 索引、API 详情、数据模型、错误码。API Documentation 是完整 HTTP 契约事实源，但不承担故事或 AC 追溯。不得包含 `BE-US-*`、`AC-BE-*`、用户故事列、AC 列、认证方式、权限要求、业务规则、业务逻辑、处理逻辑和实现逻辑。
+
+职责边界：产品权限与业务规则留在 Product Requirement；HTTP 契约留在本文件；代码落点与权限实现映射留在 Dependency Analysis。三份产物不得互相复制对方职责内容。
+
+通用约定固定包含 Base URL、成功响应结构、公共错误响应结构、时间和标识符规范；公共错误响应结构必须包含合法 JSON 示例，且示例包含顶层 `code`。所有成功与失败响应的 HTTP 状态码统一为 `200`，客户端只根据响应体顶层 `code` 判断结果，不得使用 `4xx/5xx` 表达业务失败。只有至少一个接口实际分页时才包含分页约定。非分页文档不得生成空分页章节或“不分页”占位。不输出 `kb-design-assist` 调用过程、`KB-EVIDENCE-*`、知识库/代码搜索过程、命中证据或“复用检查”章节。
 
 每个接口标题使用 `### API-001 名称`，随后写 Swagger 风格方法路径。固定子章节：基本信息、成功响应、错误响应。非认证请求头、Path 参数、Query 参数、Request Body 按适用性生成；URL 有模板参数时必须生成 Path 参数。字段层面只写名称、类型、必填/可空、格式、枚举、契约约束和语义，不写计算、转换、查询或分支逻辑。
 
-基本信息只包含 Operation ID、变更类型和幂等性，不重复 API ID。API 索引包含 API ID、Method + Path、Operation ID、用户故事、AC、变更类型。
+基本信息只包含 Operation ID、变更类型和幂等性，不重复 API ID。API 索引只包含 API ID、Method + Path、Operation ID、变更类型。索引与 API 详情必须严格双向一一对应：不得有缺失索引的详情、缺失详情的索引行、重复 API ID 或重复 Operation ID；同一 API 的 Method+Path、Operation ID 和变更类型必须完全一致。
+
+成功响应明确写 `HTTP：200` 并包含合法 JSON 示例；错误响应至少列出一个 HTTP `200` 的错误 code 和合法 JSON 示例。成功与错误 JSON 均包含顶层 `code`，且成功 code 与错误 code 必须不同；错误示例的 `code` 必须出现在错误响应表中。变更类型使用新增、修改、复用。
+
+分页接口在 Query 参数中定义每页条数参数（`pageSize` / `page_size` / `limit`）。仅 cursor、或 Query 字段名碰巧含 `page` 但无条数参数的接口，不算本契约要求的分页接口，不得据此强制生成分页约定或 page-size 行。允许值以 Product Requirement 为准：上游已给出集合时原样列出；上游确实未说明时依次使用当前有效知识库分页规范、仓库通用分页定义和默认集合 `10 | 20 | 50 | 100`。参数名和必填性优先复用 Product Requirement；PR 未规定时先采用有效知识库规范并由仓库现有约定核验。本 skill 不强制该参数为可选。只有 Product Requirement、有效知识库规范或仓库通用分页定义明确时才写默认值，不再生成 `<100`、`=100`、`>100` 分页场景。Validator 必须核对：存在 `pageSize`、`page_size` 或 `limit` Query 参数时恰好有一个“分页约定”，参数行包含数值允许集合且与分页约定一致；Product Requirement 明确允许集合时还必须与其一致；不存在这些参数时禁止“分页约定”。参数来源优先级和默认值来源继续由生成流程与 forward-test 核对。
 
-成功响应包含至少一个 2xx 和合法 JSON 示例；错误响应包含至少一个 4xx/5xx 和合法 JSON 示例。变更类型使用新增、修改、复用。
+无对应内容时省略空的 Header、Path、Query 或 Request Body 子章节。Schema 字段只在“数据模型”完整定义一次，接口详情引用 Schema。“数据模型”只定义实际使用的 Schema 和字段；“错误码”只说明 code 和可观测的触发条件，HTTP 状态统一为 `200`。字段、Response、错误码、时间与标识符等技术约定在 Product Requirement 未规定时，优先采用 `kb-design-assist` 返回的当前有效规范，再核验仓库共享定义。两个章节均不新增“复用检查”，不输出知识库或代码搜索过程，不展开业务判定或实现逻辑。
 
-分页接口在 Query 参数中定义每页条数参数：必填性为“否”，允许值完整列为 `10 | 20 | 50 | 100`。参数名优先复用仓库现有约定，例如 `pageSize`、`page_size` 或 `limit`。只有 Product Requirement 或仓库通用分页定义明确时才写默认值，不再生成 `<100`、`=100`、`>100` 分页场景。
+`mode=api-only` 与 `mode=full` 使用完全相同的 API 契约和校验规则。`api-only` 只生成本文件，不创建、覆盖或追加 `dependency-analysis.md`。
 
-“数据模型”只定义实际使用的 Schema 和字段；“错误码”只说明 HTTP 状态、code 和可观测的触发条件。两个章节均不新增“复用检查”，不输出公共定义搜索过程，不展开业务判定或实现逻辑。
+`API（Web）` 与 `API（Remote）` 使用同一契约。`API（Web + Remote）` 必须为两条实际接口分别建模，例如项目规范确定的 `GET /order/list` 与 `GET /remote/order/list`；不得把 `/remote` 当作固定前缀，Method+Path 必须来自有效规范或仓库惯例。

package/skills/analyze-product-dependencies/references/dependency-analysis-schema.md

@@ -1,28 +1,38 @@
-# Dependency Analysis V3 输出契约
+# Dependency Analysis V4 输出契约
 
 ```yaml
 ---
-artifact_version: "3.0"
+artifact_version: "4.0"
 artifact_type: dependency-analysis
 requirement_id: <与 Product Requirement 一致>
-project_root: ../../..
 analysis_scope: frontend | backend | both
-source_product_requirement: ./product-requirement.md | none
-source_api_documentation: ./api-documentation.md | none
-repository_root: ../../.. | none
 analysis_status: complete | blocked
 blocked_on: none | <原因列表>
 ---
 ```
 
-Complete 固定章节：输入与代码基线、用户故事覆盖矩阵、按 scope 的依赖详情、后端场景的 API 实现映射、跨故事共享依赖、风险与未定位项。覆盖矩阵承担全局追溯，不生成独立分析范围或追溯汇总。
+Frontmatter 只允许以上六个字段，不得增加来源、项目根、仓库路径或其他运行时字段。
 
-前端详情字段：验收标准、影响文件、页面/路由、组件、状态、API client/类型、状态与边界落点、定位证据、风险、置信度。
+Complete 固定章节：输入与代码基线、用户故事覆盖矩阵、按 scope 的依赖详情、API 实现映射、跨故事共享依赖、跨故事风险与未定位项。覆盖矩阵承担全局追溯，不生成独立分析范围、全局文件索引或追溯汇总。“输入与代码基线”记录知识检索状态 `executed-hit | executed-no-match | unavailable`；每次分析都必须真实执行知识检索，不允许未执行状态。若 complete 产物最终仍记录 `unavailable`，必须同时记录 `- 用户处置：已确认跳过知识库`；命中有效规范时可列必要的 `KB-EVIDENCE-*` 摘要。
+
+前端详情字段：验收标准、API 文档引用、影响文件、页面/路由、组件、状态、API client/类型、状态与边界落点、定位证据、风险、置信度。
 
 后端详情字段：验收标准、API 文档引用、影响文件、路由/入口、Controller/Handler、Service/领域逻辑、DTO/Schema、数据依赖、权限依赖、错误/日志/审计、测试落点、定位证据、风险、置信度。
 
-`影响文件` 是完整权威清单，每项使用唯一 `F<number>`、add/modify/reuse、真实路径和用途；其他代码落点字段引用这些编号，不重复完整路径。
+职责边界：Product Requirement 承载产品权限/业务规则；API Documentation 只承载 HTTP 契约；本文件把权限与规则映射到代码落点（如“权限依赖”），不复制完整 API 参数表、响应 JSON 或 Given/When/Then 正文。
+
+`影响文件` 是当前故事独立完整的权威清单，每项使用故事内唯一 `F<number>`、动作词（`add|modify|reuse` 或中文同义 `新增|修改|复用`）、真实路径或「未定位」、以及用途；其他代码落点字段引用当前故事编号，不重复完整路径。同一文件可在不同故事中重复出现。
+
+每个选中故事必须恰好存在一份同 ID 依赖详情；缺失、重复或出现未选中故事都必须失败。
+
+覆盖矩阵维护 `FE/BE-US → AC` 和适用的 API 引用。后端故事的“API 文档引用”列出 API ID。前端故事传入外部 API 文档时只列实际依赖的 `Method + Path`，不记录 API ID、Operation ID、文档路径或完整契约；外部文档可包含无关接口。无 HTTP 依赖的前端故事写“`不适用；本故事无 HTTP API 依赖`”，非 API 后端故事写“`不适用；触发方式为 <实际类型>`”。
+
+前端“页面/路由”必须登记 Product Requirement 的目标路由及实际代码落点，不得改变目标 URL；上游写“不适用”时不得虚构独立路由。
+
+后端 API 实现映射登记 API ID、Operation ID、Method+Path 和代码入口（具体现有路径或拟新增路径；禁止「未定位」占位）。前端使用外部 API 文档时，映射只登记被引用的 Method+Path。生成的 `api-documentation.md` 中每个 API 必须有代码入口、至少被一个 API-backed 后端故事引用且不得孤立；外部前端 API 文档不执行整份文档孤立检查。无 API 时写：`不适用。本次需求不涉及 HTTP API。`
+
+故事局部风险保留在对应故事详情；文末“跨故事风险与未定位项”只记录跨故事、跨前后端或无法归属单故事的风险，同一风险不得重复。状态、空数据、loading、error、disabled、错误文案和恢复入口必须引用项目真实枚举、组件或规范证据；未定位时写入适当风险位置，不得用通用状态名补齐。知识库证据只证明目标规范，代码证据才可证明真实文件、符号和调用关系；二者不一致时必须登记规范迁移/合规风险。知识库文档不得列为“影响文件”。`api-only` 模式不生成本产物。
 
-API 实现映射只登记 API ID、Operation ID、方法路径和代码入口。无 API 时写：`不适用。本次需求不涉及 HTTP API。`
+不得复制 AC 的 Given/When/Then 正文或完整 API 参数、响应、Schema、JSON 示例。
 
 Blocked 产物只含分析范围、输入与代码基线、阻断原因、恢复条件，不得包含确定性代码位置或 API 契约。

package/skills/analyze-product-dependencies/references/example.md

@@ -1,12 +1,12 @@
-# V3 输出示例
+# V4 输出示例
 
 ## API 索引与详情
 
 ````md
 ## 2. API 索引
-| API | Method + Path | Operation ID | 用户故事 | AC | 变更 |
-|---|---|---|---|---|---|
-| API-001 | GET /api/v1/orders/{orderId}/refund-status | getRefundStatus | BE-US-001 | AC-BE-001 | 新增 |
+| API ID | Method + Path | Operation ID | 变更类型 |
+|---|---|---|---|
+| API-001 | GET /api/v1/orders/{orderId}/refund-status | getRefundStatus | 新增 |
 
 ## 3. API 详情
 ### API-001 查询退款状态
@@ -27,13 +27,13 @@
 #### 成功响应
 - HTTP：200
 ```json
-{"data":{"refundStatus":"processing"}}
+{"code":"SUCCESS","data":{"refundStatus":"processing"}}
 ```
 
 #### 错误响应
 | 状态码 | 错误码 | 条件 |
 |---|---|---|
-| 403 | FORBIDDEN | 资源访问被拒绝 |
+| 200 | FORBIDDEN | 资源访问被拒绝 |
 ```json
 {"code":"FORBIDDEN","message":"forbidden"}
 ```
@@ -42,7 +42,7 @@
 
 无 Path、Query、Body 或专属 Header 时省略对应章节。
 
-分页接口在 Query 参数中定义可选的每页条数：
+本示例沿用项目约定，将每页条数定义为可选；实际必填性以 Product Requirement 或仓库 API 规范为准：
 
 ```md
 #### Query 参数
@@ -70,7 +70,7 @@
 ## API 实现映射
 | API | Operation ID | 方法与路径 | 代码入口 |
 |---|---|---|---|
-| API-001 | getRefundStatus | GET /api/v1/orders/{orderId}/refund-status | F1 |
+| API-001 | getRefundStatus | GET /api/v1/orders/{orderId}/refund-status | `src/refund/refund.controller.ts#getRefundStatus` |
 ```
 
-`影响文件` 是完整路径清单；其余字段使用 F 编号引用。非 API 后端故事不生成 API 文档。
+`影响文件` 是当前故事的完整路径清单；其余字段使用该故事内的 F 编号引用。API 文档不包含故事或 AC；追溯统一由 Dependency Analysis 维护。非 API 后端故事不生成 API 文档，并在“API 文档引用”中写明触发方式。

package/skills/analyze-product-dependencies/references/forward-test-cases.md

@@ -1,35 +1,110 @@
 # Forward-Test Cases
 
-## Case 1：缩小为 frontend
+在独立 agent 中逐个执行，只提供原始请求与输入产物，不泄露预期正文。
 
-使用 complete、scope 为 both 的 Product Requirement 和真实仓库，指定 `--target frontend`。核对：只生成 `dependency-analysis.md`；`analysis_scope` 为 `frontend`；不生成空 API 文档；没有后端依赖章节、`BE-US-*` 或 API 实现映射；每个 FE 故事有文件证据和状态边界落点。
+## Case 1：frontend 路由与非 API 引用
 
-## Case 2：backend API
+使用 complete、scope 为 frontend 的 Product Requirement，其中页面路由为 `/account/orders`，故事无 HTTP 依赖。核对：只生成 Dependency Analysis；详情保留目标 URL；“API 文档引用”写“`不适用；本故事无 HTTP API 依赖`”；API 实现映射明确不适用；不生成空 API 文档。
 
-```text
-Use $analyze-product-dependencies with a complete backend Product Requirement whose BE-US-001 trigger is API, plus a repository.
-```
+## Case 2：无独立路由组件
 
-核对：两个文件写入 Product Requirement 的同一需求目录；API 索引覆盖 API ID、Operation ID、方法路径、故事和 AC；Dependency 的 API 映射只保留 API ID、Operation ID、方法路径和代码入口；影响文件使用唯一 F 编号。
+Product Requirement 页面路由写“`不适用；嵌入 /account/orders 页面`”。核对：Dependency 不虚构独立 URL，定位所属页面与组件落点。
 
-同时核对：API 文档不含认证方式、权限要求、业务规则、业务逻辑或实现逻辑及其相关内容；字段与 code 在生成前内部搜索共享定义，但 API 文档不输出“复用检查”或搜索证据。若接口分页，每页条数参数必须可选，允许值完整包含 `10/20/50/100`。
+## Case 3：backend API
 
-## Case 3：backend 定时任务
+使用 complete backend Product Requirement，`BE-US-001` 触发方式为 `API（Web）`。核对：API Documentation 和 Dependency Analysis 来自同一次侦察及同一规范中间模型；API 文档索引只有 API ID、Method + Path、Operation ID、变更类型，不含 `BE-US-*`、`AC-BE-*`、故事列或 AC 列；Dependency 覆盖矩阵关联故事、AC 与 API。
 
-使用触发方式为定时任务的归档需求。核对：只生成 Dependency；`source_api_documentation: none`；API 映射写不适用；重点定位 scheduler、job、幂等、批次、数据库和恢复测试。
+## Case 4：非分页 API
 
-## Case 4：业务契约缺失
+使用非分页查询 API。核对：通用约定保留 Base URL、成功响应结构、公共错误响应结构及 JSON、时间和标识符规范；成功与错误响应均使用 HTTP 200，响应体顶层 code 不同，客户端仅根据 code 区分结果；不生成“分页约定”或“不分页”占位。
 
-使用缺少权限范围或输出语义的 API 型 Product Requirement。核对：不得发明产品决策；生成 blocked 依赖产物并返回上游补充。
+## Case 5：分页 API
 
-## Case 5：不存在的目标能力
+分别覆盖：
+- A：Product Requirement 未给出允许值，知识库规范为 `20/50/100` → API 文档使用 `20/50/100`。
+- B：Product Requirement 明确允许值为 `5/10/20` → API 文档必须与之完全一致，不得改回默认集合。
+- C：每页条数参数分别为必填与可选 → 两种文档都应通过。
+- D：实际分页但缺少“分页约定” → validator 与 forward-test 都判定失败。
+- E：非分页 API 出现“分页约定”或“不分页”占位 → validator 与 forward-test 都判定失败。
+- F：page-size 参数允许值与“分页约定”或 Product Requirement 明确集合不一致 → validator 与 forward-test 都判定失败。
+- G：Product Requirement、知识库和仓库均未给出允许值 → API 文档才使用默认 `10/20/50/100`。
 
-代码库中没有对应实现。核对：允许结论为新增，但证据必须展示已搜索范围和邻近模式；不得虚构文件已经存在。
+## Case 6：backend 定时任务
 
-## Case 6：缩小分析范围
+使用触发方式为定时任务的归档需求。核对：只生成 Dependency；故事“API 文档引用”写“`不适用；触发方式为 定时任务`”；API 映射写不适用；重点定位 scheduler、job、幂等、批次、数据和恢复测试。
 
-使用 scope 为 both 的 Product Requirement，并指定 `target=backend`。核对：输入门禁通过；只要求 BE 故事覆盖；Dependency 和适用的 API 文档使用 `analysis_scope: backend`，不强制生成前端详情。
+## Case 7：API 必要业务契约缺失
 
-## Case 7：缺少输入
+分别删除 API 型故事输出规范中的输入语义、输出语义、权限规则、业务规则、安全要求或错误与边界。核对：Product Requirement Input Validator 失败，不重新评价 AC 文案风格。
 
-分别缺少 Product Requirement 和代码仓库。核对：只生成四个固定章节的 blocked Dependency；前者使用 `source_product_requirement: none`，后者允许 `repository_root: none`；不得生成 API 文档或确定性代码位置。
+## Case 8：Input Validator 不重复上游质量检查
+
+使用已通过上游校验且具备故事、同 ID 输出规范、AC ID、触发方式、页面路由或 API 必要业务契约的 Product Requirement，但 AC 正文风格不是下游偏好的写法。核对：Input Validator 仍通过。
+
+## Case 9：完整故事文件清单
+
+使用两个故事且二者影响同一文件。核对：每个故事都有独立完整的“影响文件”清单；F 编号在故事内重新开始并只在该故事内引用；不生成全局文件索引。
+
+## Case 10：故事局部风险
+
+制造一个仅属于 `FE-US-001` 的路由冲突和一个跨前后端共享契约风险。核对：路由冲突只写在故事详情，跨域风险只写在文末“跨故事风险与未定位项”，同一风险不重复。
+
+## Case 11：API 覆盖与孤立检测
+
+让 API-backed 故事漏掉 API ID、API ID 缺少代码入口、或 API 文档新增未被任何故事引用的 API。核对：三种情况都失败；纯前端或非 API 后端故事使用带原因的“不适用”可以通过。
+
+## Case 12：内容边界
+
+尝试把 Given/When/Then 正文、完整 Query 参数、响应、Schema 或 JSON 示例复制到 Dependency Analysis。核对：校验失败；API 实现映射只保留 API ID、Operation ID、Method + Path 和代码入口。
+
+## Case 13：代码位置 unknown
+
+代码库中没有目标能力。核对：继续生成 Dependency，记录搜索范围、原因、下一步和 low 置信度；不向用户询问代码位置，也不虚构文件。
+
+## Case 14：项目规范
+
+使用包含共享状态枚举、空状态组件和同类页面的仓库，并让 `kb-design-assist` 返回当前有效设计系统规范。核对：先获得精简规范证据；当前宿主支持隔离的只读代码侦察 agent 时委派其核验代码落点，不支持时由当前 agent 执行同等范围的定向搜索；Dependency 使用真实枚举、组件、文案与恢复方式，同时区分 `KB-EVIDENCE-*` 与代码证据，不套用 generic 模板。
+
+## Case 15：api-only
+
+使用 complete backend API Product Requirement、真实仓库和 `--mode api-only`。核对：只创建或更新 `api-documentation.md`，已有 Dependency 字节不变；只运行 Product Requirement Input 和 API 两个当前产物校验器，不运行 Dependency 校验器或 validator matrix。
+
+## Case 16：非法 api-only
+
+分别使用 `--mode api-only --target frontend` 和没有 API 型后端故事的需求。核对：停止并报告原因，不生成空 API 文档或 blocked Dependency。
+
+## Case 17：普通执行验证范围
+
+分别运行 frontend、backend 非 API、backend API、api-only 和 blocked 流程。核对：只运行各自当前产物 validator；`test-validators.mjs` 仅在维护或发布回归时运行。
+
+## Case 18：后端规范知识检索
+
+使用 API 型后端故事，并让 `kb-design-assist` 命中 Controller/Service/Entity/Response、Remote、Web API、错误码清单和服务 `interfaces.md`。核对：在代码侦察前执行定向知识检索；API 中间模型优先采用当前有效规范并由仓库共享定义核验；API Documentation 只呈现最终 HTTP 契约，不包含 `KB-EVIDENCE-*`、知识库路径、调用过程或“复用检查”。
+
+## Case 19：知识库与代码现状冲突
+
+知识库要求统一 `ApiResponse` 和新的错误码体系，仓库目标模块仍使用旧响应类型。核对：当前影响文件与调用关系以代码证据为准；有效知识库规范作为目标约束；Dependency 登记规范迁移/合规风险，不把知识库文档列为影响文件，也不静默把旧实现当作规范。
+
+## Case 20：知识库强制前置、未命中与不可用
+
+分别构造“看似不涉及项目规范”的简单故事、相关查询无结果和 `kb-design-assist` 调用失败。核对：简单故事仍先从故事、输出规范和 AC 提取检索计划并真实调用，不允许 `not-executed`；无结果记录 `executed-no-match` 并把项目规范检索降级为受限、定向的代码库搜索；调用失败记录 `unavailable`，必须先说明失败原因并询问用户选择“修复后重试”或“跳过知识库”，未选择前不得预扫描项目资料、侦察代码或生成 complete 产物；选择修复后按重试结果继续，明确选择跳过后才允许降级；仍未查明时按 unknown 处理。不得模拟知识库结果或绕过确认门禁。
+
+## Case 21：Web + Remote 生成两个 API
+
+使用触发方式为 `API（Web + Remote）` 的订单列表故事。核对：同一故事至少引用两个 API ID，分别生成项目规范确定的 Web 与 Remote Method+Path；`/order/list` 和 `/remote/order/list` 仅作为可能示例，不得把 `/remote` 前缀写成固定规则。
+
+## Case 22：frontend 外部 API 文档
+
+使用 scope 为 frontend 的 Product Requirement，并传入需求目录外且包含多个无关接口的 Markdown API 文档。核对：Dependency 只记录当前故事实际引用的 Method+Path；不记录 API ID、Operation ID、文档路径或完整契约；无关接口不触发孤立错误；未传 `--api-doc` 或引用不存在的 Method+Path 时校验失败。
+
+## Case 23：项目资料预扫描
+
+知识库状态确定后提供三个 `ai_workspace` 目录。核对：常规代码侦察前按 `project-how-to`、`code-specification`、`project-business` 顺序枚举并定向读取；缺失目录不阻断；知识库、项目资料和代码冲突时保留差异证据。
+
+## Case 23A：知识库与代码侦察顺序
+
+使用包含状态、权限和 API 线索且仓库已有相似实现的故事。核对执行轨迹严格为：从选中故事、输出规范和 AC 提取检索计划 → 调用 `kb-design-assist` → 项目资料预扫描 → 定向代码侦察 → 汇总双证据与风险。不得先搜索仓库再补做知识库检索。
+
+## Case 24：严格索引与详情唯一性
+
+分别向 V4 frontmatter 注入仓库路径、在 API 索引增加没有详情的 API、修改索引中的 Operation ID、为同一故事复制一份依赖详情，并让两个输入故事复用同一 AC ID。核对：额外 frontmatter 字段、非双向一一对应的 API 索引、重复故事详情和重复 AC ID 都被 validator 拒绝。

package/skills/analyze-product-dependencies/references/input-contract.md

@@ -1,11 +1,34 @@
 # Product Requirement 输入契约
 
-首选输入为 complete V3 `product-requirement.md`。迁移期允许读取 complete V2，但不修改上游产物；新产物始终使用 V3。
+首选输入为 complete V4 `product-requirement.md`。迁移期允许读取 complete V2/V3，但不修改上游产物；新产物始终使用 V4。
 
-V3 必须包含精简用户故事、同 ID 输出规范和嵌入规范的 AC。故事与规范一一对应，故事 AC 引用与规范内 AC 完全一致。V2 继续按其原有嵌入故事的 AC 读取。
+## 校验边界
+
+输入校验器只确认下游能够安全消费 Product Requirement，不重复上游的全部文案与 AC 质量检查。
+
+不重新评价：Given/When/Then 文本质量、最低条目数量、完整决策追溯、Clarification 状态、实现细节泄漏禁语、分页默认补齐策略，以及其他只属于上游生成质量的禁止措辞。实现泄漏禁语信任上游交付路径；本 skill 不复查。
+
+交接门禁：下游只接受上游按交付路径校验通过的 complete Product Requirement（不得携带 `--allow-pending`）。首选 complete V4；迁移期仍可读取 V3 和非 API 的 complete V2（见下文）。本 skill 的 `--target` 可取上游 `analysis_scope` 的子集，不会改写上游产物。
+
+## V3/V4 要求
+
+选中范围内至少一个用户故事、同 ID 输出规范和嵌入规范的 AC ID。故事与规范一一对应，故事 AC 引用与规范内 AC ID 完全一致。前端故事必须包含页面路由；无独立路由时使用“不适用”并说明所属页面。后端故事必须包含合法触发方式。
+Product Requirement frontmatter 只允许对应版本契约定义的字段；AC ID 在整个输入中必须全局唯一。
+
+API 型后端故事必须具备下游建模最小业务契约字段：输入语义、输出语义、权限规则、业务规则、安全要求、错误与边界。触发方式必须明确为 `API（Web）`、`API（Remote）` 或 `API（Web + Remote）`；迁移期 V3 中笼统的 `API` 也必须返回上游确认范围。Web 与 Remote 都生成 HTTP API 契约，Web + Remote 生成两个独立 API。上游输出规范中的「数据读写」「幂等与并发」不作为本 skill 输入门禁字段。
+
+## V2 迁移期
+
+V2 按原有“AC 嵌在故事内”的方式读取，不要求独立输出规范章节。V2 + API 触发故事时，禁止生成 API Documentation 与 complete Dependency Analysis 中的 API 映射路径；输入校验器对此组合直接失败，要求先用需求分析 skill 升级为 V4。非 API 的 V2 仍可做依赖落点分析。
+
+## 仓库、范围与模式
 
 必须提供存在、可读的代码仓库。Product Requirement 位于 `<project-root>/docs/product-analysis/<requirement-id>/`；新增产物写回同目录并继承 ID。显式 target 必须是上游 scope 的子集。
 
-任一选中后端故事的触发方式为 API 时生成 `api-documentation.md`；非 HTTP 触发不得生成空 API 文档。业务输入输出、权限、核心规则或安全边界缺失时阻断。
+`mode` 使用 `full` 或 `api-only`，默认 `full`。`api-only` 只适用于 target 为 `backend|both` 且至少一个选中后端故事的触发方式为 API；它只生成 `api-documentation.md`，不得创建或修改 `dependency-analysis.md`。其代码侦察仍必须覆盖仓库 API 规范、共享 Schema、统一响应/错误和分页约定。
+
+任一选中后端故事的触发方式为 API 时生成 `api-documentation.md`；非 HTTP 触发不得生成空 API 文档。`frontend` 不新生成 API 文档；可通过 `--api-doc <path>` 消费任意可读 Markdown API 文档，只把当前故事引用且能核验的 Method+Path 写入 Dependency Analysis。外部文档可包含无关接口，不执行整份文档孤立检查，也不持久化文档路径。业务契约字段缺失时阻断；分页契约按 `api-documentation-schema.md` 生成。
+
+## 阻断产物
 
-门禁失败时 Dependency Analysis 只包含分析范围、输入与代码基线、阻断原因、恢复条件。`blocked_on` 使用 requirement-missing、requirement-invalid、requirement-not-complete、repository-missing、repository-unreadable、scope-mismatch、missing-stories、missing-acceptance、api-business-contract-incomplete。
+`full` 门禁失败时：若可从 Product Requirement 路径、用户显式 `requirement_id` 或输出路径确定需求目录，则写入 blocked Dependency Analysis（只含分析范围、输入与代码基线、阻断原因、恢复条件）；否则不写产物，只在会话报告。`blocked_on` 使用 requirement-missing、requirement-invalid、requirement-not-complete、repository-missing、repository-unreadable、scope-mismatch、missing-stories、missing-acceptance、api-business-contract-incomplete、api-surface-unconfirmed。`api-only` 门禁失败时不生成占位产物，只在会话中报告阻断原因与恢复条件。

package/skills/analyze-product-dependencies/references/kb-integration.md

@@ -0,0 +1,64 @@
+# kb-design-assist 接入契约
+
+每次依赖分析都必须先根据选中故事、输出规范和 AC 使用当前宿主原生的 skill 加载机制调用第三方 `kb-design-assist`，再预扫描项目资料和探索代码库。即使故事简单或未显式提到项目规范也不得跳过。知识库用于确定“项目要求怎样设计”，代码库用于证明“当前实现在哪里、怎样连接”；两者证据不得互相替代。
+
+## 调用输入
+
+先从选中故事、同 ID 输出规范和 AC 提取业务词、领域对象、状态/边界、权限、接口形态与技术约定，再向 `kb-design-assist` 提供：
+
+- 可识别的项目、服务或知识库范围；无法确定时使用当前项目上下文，不得臆造范围。
+- 已归一化的 `target`、`mode`、选中故事、同 ID 输出规范、AC、领域对象和技术关键词。
+- 与当前故事直接相关的规范类别，不做无边界扫描。
+- 返回要求：规范结论、文档标题与章节/定位、版本或生效状态、适用服务/范围、置信度、冲突与未定位项。
+
+按场景优先查询：
+
+- frontend：设计系统、共享组件、状态枚举、交互/文案、错误展示和恢复入口。
+- backend/API：Controller/Handler、Service/Domain Service、Entity、DTO/Schema、Response、Remote 接口、Web API、路由/版本、统一响应外壳、错误码清单、分页、时间、标识符和服务 `interfaces.md`。
+- backend 非 API：与触发方式对应的任务、事件、消息、数据、幂等、并发、日志和审计规范。
+
+知识库状态已确定或用户确认跳过后，依次预扫描 `<project-root>/ai_workspace/project-how-to`、`code-specification`、`project-business`，再开始常规代码侦察。目录缺失记录 `not-found` 并继续；项目资料可补充项目约定和业务背景，但不得替代真实代码落点。
+
+## 结果状态
+
+当前宿主可发现 `kb-design-assist` 时，使用宿主原生的 skill 加载机制调用。知识检索必须记录一种真实状态：
+
+- `executed-hit`：已执行并命中可定位、适用且有效的规范。
+- `executed-no-match`：已执行，但没有与当前问题相关的结果。
+- `unavailable`：`kb-design-assist` 未安装、不可发现、调用失败或无法访问目标知识库。
+
+未执行知识库检索属于流程违规，不得开始代码侦察或生成产物。未执行时不得声称“未命中”；调用失败时不得模拟结果。非 `executed-hit` 不得伪装为 `executed-hit`。
+
+状态为 `executed-no-match` 时直接触发降级：在现有仓库中执行受限、定向的代码库搜索，仍未查明时按 unknown 处理。`executed-hit` 不触发规范降级，但真实代码落点侦察仍照常执行。
+
+状态为 `unavailable` 时不得直接降级。立即停止后续知识查证与 complete 产物生成，向用户说明可观察到的失败原因，并单独询问选择：
+
+1. **修复后重试**：等待用户修复安装、发现、调用或访问问题，再重新调用 `kb-design-assist`；以重试后的真实结果状态继续流程。
+2. **跳过知识库**：仅在用户明确同意后，记录 `- 用户处置：已确认跳过知识库`，再执行与 `executed-no-match` 相同的受限、定向代码库降级；仍未查明时按 unknown 处理。
+
+用户未明确选择前保持阻断，不得自动重试、自动跳过、自动降级或把 `unavailable` 改写为其他状态。依赖分析为定位真实代码落点而必须执行的代码侦察不属于降级，但不得借此绕过该确认门禁，代码证据也不得被包装成知识库规范。
+
+## 双证据规则
+
+每条有效知识结果使用 `KB-EVIDENCE-*`，记录规范结论、来源文档及定位、版本/生效状态、适用范围和置信度。代码事实继续使用仓库路径、符号、import、调用、路由或配置证据。
+
+- `KB-EVIDENCE-*` 只能证明目标规范，不能把文件、类、路由或调用关系标记为 `confirmed`。
+- 代码证据只能证明当前实现，不能覆盖 complete Product Requirement 或有效的目标规范。
+- 知识库与代码一致时，规范证据与实现证据并列保留。
+- 知识库与代码不一致时，按实际代码生成当前影响落点，并登记规范迁移/合规风险；不得静默选边。
+- 过期、适用范围不明、互相冲突或无法定位来源的知识结果只能作为风险或 unknown。
+
+技术设计来源按职责处理：
+
+1. complete Product Requirement 决定业务目标、权限、规则和用户可见行为。
+2. 当前有效知识库规范决定 PR 未规定的项目技术约定。
+3. 仓库共享定义和现有接口惯例用于核验、复用及确定真实落点。
+4. 相似实现和通用规则仅在以上来源均未定义时使用。
+
+分页允许值始终以 Product Requirement 为准；旧版或异常输入确实未给出时，依次使用有效知识库分页规范、仓库通用分页定义和固定兜底 `10/20/50/100`。参数名、默认值、统一响应、错误码、时间和标识符格式在 PR 未规定时优先使用有效知识库规范，再核验仓库共享定义。
+
+## 产物边界
+
+- Dependency Analysis 可在“输入与代码基线”“定位证据”或风险中引用必要的知识库规范证据，但必须同时保留代码落点证据；不得把知识库文档当成影响文件。
+- API Documentation 只输出最终 HTTP 契约，不输出 `kb-design-assist` 调用过程、`KB-EVIDENCE-*`、文档路径、命中日志或“复用检查”。
+- `api-only` 同样必须先执行需求驱动的知识检索，但不得因此创建或修改 Dependency Analysis。

package/skills/analyze-product-dependencies/references/scouting-rules.md

@@ -10,18 +10,30 @@
 
 ## 搜索顺序
 
-1. 阅读仓库级指令、README、技术栈配置和相关架构文档。
-2. 可用时优先使用 CodeGraph 定位符号、引用和调用关系。
-3. 使用 `rg --files` 建立文件范围，使用 `rg` 搜索路由、组件、接口、字段、状态和领域术语。
-4. 阅读入口文件、直接依赖、邻近实现和共享 helper。
-5. 只沿与用户故事相关的引用继续扩展，避免无边界扫描。
+先从选中故事、输出规范和 AC 形成定向检索计划，再读取并执行 `kb-integration.md`，直接沿用其中的状态机、结果结构和降级边界；知识库门禁通过后才能开始代码探索。知识库检索不得代替代码侦察。
+
+当前宿主支持隔离的只读代码侦察 agent 时，优先将代码探索交给该 agent；委派内容仅包含选中故事、输出规范、AC、待查问题、允许搜索的范围和适用的知识库规范结论，并只接收精简结论、证据路径/符号、置信度、规范冲突与未定位项。当前宿主不支持该能力时，由当前 agent 先限定故事、问题、目录或关键词，只沿直接相关引用定向扩展，不做无边界扫描；不得因此阻断流程或扩大搜索范围，结果同样只保留结论、必要证据、置信度与未定位项。
+
+1. 按 `kb-integration.md` 完成与选中故事直接相关的项目规范检索并记录真实状态；每次分析都必须真实执行。状态为 `executed-hit` 或 `executed-no-match`，或 `unavailable` 后用户明确确认跳过，才进入后续步骤；门禁通过后不得跳过本 skill 必需的真实代码落点侦察。
+2. 知识库状态已确定或用户确认跳过后，依次预扫描 `<project-root>/ai_workspace/project-how-to`、`code-specification`、`project-business`。先用 `rg --files` 枚举，再读取入口文档及与选中故事直接相关的文件；缺失目录记录 `not-found` 并继续。
+3. 执行侦察的 agent 阅读仓库级指令、README、技术栈配置、设计系统和相关架构文档，用于核验知识库规范和发现差异。
+4. 当前环境提供 CodeGraph 或等价的符号与引用分析能力时优先使用；不可用时通过文本搜索、import、调用、路由注册、类型引用和配置证据完成核验。
+5. 优先使用 `rg --files` 建立文件范围，使用 `rg` 搜索路由、组件、接口、字段、状态和领域术语；没有 `rg` 时使用宿主提供的等价只读文件搜索能力，不得降低证据标准。
+6. 阅读入口文件、直接依赖、邻近实现和共享 helper。
+7. 只沿与用户故事相关的引用继续扩展，避免无边界扫描。
+8. 返回结构化精简结果后结束；不要把大量源码、搜索日志或无关文件带回当前会话。
 
 ## 事实与推断
 
+- `KB-EVIDENCE-*`：当前有效规范的结论、文档定位、版本/生效状态、适用范围与置信度；只能证明目标规范，不能证明代码落点。
 - `confirmed`：文件存在，并有 import、调用、路由、注册、类型或配置证据。
 - `inferred`：根据命名和邻近模式推断，但没有完整引用证据；置信度只能为 medium 或 low，证据必须分别写明已观察事实和推断链，不得使用“已确认”措辞。
 - `unknown`：搜索后仍无法定位。
 
+知识库规范与代码实现一致时并列记录两类证据；不一致时以代码证据描述当前落点，并把偏离有效规范登记为故事风险或跨故事风险。过期、范围不明、互相冲突或无来源定位的知识结果不得标记为有效规范。
+
+unknown 不自动触发本 skill 的用户澄清。Product Requirement 已明确目标行为而仅代码位置、符号或复用点未知时，继续生成 Dependency Analysis，并在对应故事风险、影响文件或跨故事未定位项中记录搜索范围、原因、下一步和 low 置信度。影响文件路径可为「未定位」；但「API 实现映射」的代码入口不得写「未定位/未知/N/A/不适用」——新增接口写拟新增路径，修改/复用接口必须给出具体现有路径，否则将该 API 从本轮文档与映射中排除并记入跨故事未定位，或阻断 complete。缺失 API 业务契约字段（输入语义、输出语义、权限规则、业务规则、安全要求、错误与边界）或验收所需产品决策时，停止生成 complete 产物并返回上游需求分析澄清。
+
 每项记录证据，例如：路由注册、组件 import、service 调用、repository 注入、类型引用或配置项。不要只凭文件名断言依赖。
 
 ## 前端必查项
@@ -31,6 +43,7 @@
 - hooks、状态管理、缓存和请求层。
 - API client、类型定义、权限控制和错误展示。
 - normal、loading、empty、error、disabled 及输出规范中的边界处理落点。
+- 状态变量、空数据、loading、error、disabled、错误文案和恢复入口先通过 `kb-design-assist` 检索设计系统、状态枚举和共享组件规范，再核验仓库级指令、真实组件与同类页面；记录准确枚举、组件、规范证据和代码证据。找不到规范时标为 unknown，不得套用通用模板。
 
 每个 `FE-US-*` 都必须单独输出，不能只给一份页面级汇总。
 
@@ -41,14 +54,16 @@
 - repository、数据模型、查询与写入路径。
 - 鉴权、权限范围、幂等、并发和错误映射。
 - 事件、任务、外部服务、配置、日志和审计。
-- API 场景额外检查路由前缀、版本策略、HTTP 方法惯例、统一响应外壳、分页、时间和标识符格式，以及相似接口的 Swagger/OpenAPI 注释模式。
-- 字段定义前搜索共享 DTO/Schema、OpenAPI components、基础响应类与分页类；命中时复用而不复制定义。搜索与复用判断只用于内部建模，不输出到 API 文档。
-- 返回 code 定义前搜索全局错误枚举、异常到 code 的映射、错误响应外壳与相似接口；命中时复用，未命中才允许局部新定义。搜索与复用判断只用于内部建模，不输出到 API 文档。
-- 分页接口确认仓库既有参数名和默认值；每页条数参数必须为可选，允许值为 `10 | 20 | 50 | 100`。
+- API 场景先通过 `kb-design-assist` 检索 Controller/Handler、Service、Entity、DTO/Schema、Response、Remote、Web API、错误码、分页、时间、标识符和服务 `interfaces.md`，再检查仓库路由前缀、版本策略、HTTP 方法惯例、统一响应外壳及相似接口的 Swagger/OpenAPI 注释模式。
+- Web 与 Remote 都按 HTTP API 处理。`API（Web + Remote）` 为同一业务能力分别定位两条接口；例如 `/order/list` 与 `/remote/order/list` 仅是可能形态，Remote 前缀必须由有效规范、项目资料或仓库惯例证明。
+- 后端状态枚举、空结果语义、错误映射和兜底策略必须遵循项目共享定义及同类服务规范；本 skill 输出的成功与失败 HTTP 状态统一为 `200`，只通过响应体顶层 `code` 区分。Product Requirement 明确行为与现状冲突时保留需求并登记风险。
+- 字段定义前先检索有效知识库 DTO/Schema、Response 与接口规范，再核验仓库共享 DTO/Schema、OpenAPI components、基础响应类与分页类；命中时复用而不复制定义。搜索与复用判断只用于内部建模，不输出到 API 文档。
+- 返回 code 定义前先检索有效知识库错误码清单及映射规范，再核验仓库全局错误枚举、异常到 code 的映射、错误响应外壳与相似接口；命中时复用，未命中才允许局部新定义。成功与失败 code 必须不同，且 HTTP 状态不得参与业务结果判断。搜索与复用判断只用于内部建模，不输出到 API 文档。
+- 分页接口：每页条数允许值以 Product Requirement 为准；上游确实未说明时依次使用有效知识库分页规范、仓库通用分页定义和默认集合 `10 | 20 | 50 | 100`。参数名、必填性与默认值优先复用 Product Requirement；PR 未写明时先采用有效知识库规范并由仓库通用分页定义核验，不得擅自改变 PR 已确认的必填性。
 
 每个 `BE-US-*` 都必须单独输出，不能只给一份服务级汇总。
 
-API 技术设计优先级为：Product Requirement 已确认业务契约 > 代码库现有 API 规范 > 相似 API 模式 > 通用 REST 规则。现有实现不得覆盖已确认需求；业务语义缺失时阻断。
+API 技术设计优先级为：Product Requirement 已确认业务契约 > 当前有效知识库 API 规范（仅填补 PR 未写明的技术惯例）> 代码库共享定义和现有 API 惯例 > 相似 API 模式 > 通用 REST 规则。现有实现与知识库规范均不得覆盖已确认需求；业务语义缺失时阻断。
 
 ## 未定位项