@tea-agent/loop-agent 0.33.1 → 0.33.3

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 规则。现有实现与知识库规范均不得覆盖已确认需求；业务语义缺失时阻断。
 
 ## 未定位项