@xgent-ai/skills 0.7.1 → 0.7.3

package/skills/review-dev-plan/SKILL.md

@@ -115,6 +115,6 @@ $review-dev-plan goal/LOGIN.md，对照 goal/LOGIN.review.md 复审修复效果
 
 ## 项目状态回写
 
-若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按仓内协议更新受影响对象的当前状态与来源链接，必要时维护索引；v4 日常直接更新当前页，事件留存条件或旧版事件要求以仓内协议为准；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
 
 每次实际评审登记独立评审 ID、计划版本、覆盖范围、建议状态与报告路径；复审关联前轮。评审建议与计划自报状态分别保留，当前就绪按台账协议核对证据，不直接改原计划；建议 Ready 不表示已实施。

package/skills/review-prd/SKILL.md

@@ -110,6 +110,6 @@ PRD 与基线：{PRD 绝对路径及版本；代码仓根、commit/dirty、日
 
 ## 项目状态回写
 
-若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按仓内协议更新受影响对象的当前状态与来源链接，必要时维护索引；v4 日常直接更新当前页，事件留存条件或旧版事件要求以仓内协议为准；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
 
 每次实际评审登记独立评审 ID、PRD 版本、覆盖范围、原结论与报告路径；复审关联前轮，保留历史，不因通过改写 PRD 实施状态。台账更新属于已有跟进协议的产物索引，不修改原 PRD。

package/skills/review-prd-dev-gaps/SKILL.md

@@ -107,6 +107,6 @@ $review-prd-dev-gaps docs/PRD-login.md goal/LOGIN.md goal/LOGIN-gaps.md，对照
 
 ## 项目状态回写
 
-若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按仓内协议更新受影响对象的当前状态与来源链接，必要时维护索引；v4 日常直接更新当前页，事件留存条件或旧版事件要求以仓内协议为准；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
 
 登记独立差异核查对象及 PRD/计划关联、版本、待决与 follow-up 去向；复审关联前轮，保留未覆盖 G-ID 及历史结论。新 gaps plan 保持独立对象，关联原计划和差异 ID，不改变原计划的历史完成记录。

package/skills/review-ui/SKILL.md

@@ -105,6 +105,6 @@ description: 用于界面实现后的 UI/UX 验收或修复复审；不用于代
 
 ## 项目状态回写
 
-若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存及 managed 能力异常时的只读边界优先，登记失败须说明，不影响如实交付已完成的原产物。
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按仓内协议更新受影响对象的当前状态与来源链接，必要时维护索引；v4 日常直接更新当前页，事件留存条件或旧版事件要求以仓内协议为准；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存及 managed 能力异常时的只读边界优先，登记失败须说明，不影响如实交付已完成的原产物。
 
 每轮实际评审都登记独立的评审 ID，写明被测版本、目标指纹、范围、判定、分数和报告路径；复审关联前轮。协议的 `review_type` 没有 UI 类型时，登记为 `other`，并在摘要注明「UI 验收评审」。通过验收不能登记为已合并、已发布或产品终验通过。

package/skills/spec-human-decision/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: spec-human-decision
+argument-hint: "<PRD/Dev-plan路径/链接/内容> [功能ID/期次/范围] [输出路径] [仅讨论]"
+description: 用于用户要求逐项确认 PRD 或开发计划中的功能取舍；不用于质量评审、从零写文档或执行开发。简述功能、价值及计划中的做法，经确认、驳回、修改后修订文档。
+---
+
+# spec-human-decision · 功能逐项确认
+
+把已有 PRD 或 Dev-plan 中要开发的功能讲清楚，让用户逐项决定，再把决定落实成一致的文档。回复与问答语言跟随用户。
+
+## 适用与边界
+
+- 用户要求逐项过功能、确认做不做、调整需求或实现取舍时使用。普通撰写用 `prd` / `dev-plan`，质量评审用 `review-prd` / `review-dev-plan`，按报告改稿用 `apply-doc-review`；这些技能无需成为本技能的安装依赖。
+- 调用即包含按本次决定修订指定文档，无需每项再问是否允许改稿。用户限定仅讨论、不保存或另存时照办；背景引用与关联文档只读，未纳入的上游/下游只列同步需求。不实施代码、不更新 SPMS/Issue、不发送或发布文档。
+- **PRD 保持产品边界**：讲清做什么、为什么、怎样算满足；实现方案只属于开发计划，测试脚本不写进 PRD。完整需求与分期分开，不把本期不做自动解释为终局删除。
+- **计划保持事实与范围边界**：做法来自本次读过的文档与必要代码事实；未知不编造，外部依赖不自动转成本方开发。保留适用的实施协议、稳定 ID、进度与历史证据；文档确认不能冒充开发或验收完成。
+- **正文只保存最终结论**：需求/方案、必要理由与来源、约束及未决事项属于原文；确认/驳回经过、问答轮次和写作用了什么技能只进决定记录。计划排除项直接写最终范围及依据，不新增“本轮确认/驳回”“刚才”等依赖当前对话的措辞；必要来源写为“用户 YYYY-MM-DD 决定”。
+- **决定与就绪分别判断**：用户确认是功能取舍的结论，不代替技术评审、事实核实或验收。关键范围、安全、数据、外部契约或 NFR 未决时保留阻塞；不凭确认数量把计划改成 `Ready`。
+
+## 1. 读文档，列出待决功能
+
+1. 从参数及已有上下文定位目标，读取适用仓库规则和完整文档，记下路径、当前版本与用户限定范围。续接时读取已有决定记录，比对内容与范围后沿用仍有效的答复。没有目标或多个候选无法消歧时才问；链接用当前可用方式读取，截断内容补读后再用。
+2. 抽取范围内要开发的每项能力，以及会改变其行为、权限、关键 NFR 或验收的独立取舍。按用户能独立决定、能独立验收的能力拆分，不按章节、文件、函数或施工步骤逐个提问；能分别接受或拒绝的功能不能合并成一票。
+3. 沿用需求 ID；没有 ID 时用临时 `D1…Dn` 对应原文位置，不冒充需求系统的真实编号。建立简短台账：功能/来源段落 → 当前内容 → 用户选择及修改说明 → 最终内容 → 关联影响。多文档用路径与 ID 联合定位，重复表述映射到同一决定。
+4. 先处理会影响其他功能的前置决定。只确认某期时说清本次范围，其他期次不受这次取舍自动裁剪。本轮已有明确且仍适用的答复直接沿用，文档中的旧“已确认”标记不能代替本轮未给出的答复。
+5. 功能或价值写得含糊时先查相关材料；仍缺依据就直接写“文档未说明”，让用户修改补充，不替用户发明理由。没有可确认的开发功能时如实结束，不造空清单。
+
+## 2. 每项只讲清必要信息
+
+默认一次确认一项，收到有效答复后再推进。每个字段通常一句话，使用用户能理解的语言，保留会改变选择的关键限制、代价或依赖；不堆背景和术语，也不以简短为由隐藏取舍。
+
+```text
+[2/6] FR-02 · 导出订单（PRD §3.2）
+是什么：把选中的订单下载为 CSV。
+为什么：方便财务在现有表格里对账。
+怎么做：复用订单查询和权限校验，生成 CSV 后下载。（仅开发计划）
+影响：只导出当前用户有权查看的订单。（有关键影响时才写）
+请选择：确认 / 驳回 / 修改；修改请附说明。
+```
+
+这是表达形状的示例，不是可照抄的事实。PRD 不补“怎么做”；开发计划用一句话概括原计划的主要落点与路径，必要时解释关键方案代价；缺做法就明示待补，不能把临时设想写成原方案。
+
+## 3. 用当前 agent 的交互工具收取决定
+
+优先使用当前环境**实际可用且允许本类问答**的工具，例如 `AskUserQuestion`、`request_user_input`、`request_user_input_async` 或等价能力。读取真实 schema，遵循模式、题数和字段限制，不凭技能名猜参数，不为调用工具擅自切换模式。工具不可用或不适用时，在聊天中给同一项、同一组选项并等待答复。
+
+每题单选，业务选项按以下顺序固定为三个，含义一致：
+
+| 选项 | 含义与处理 |
+| --- | --- |
+| 确认 | 接受当前展示版本，纳入最终文档。 |
+| 驳回 | 不纳入本次确认范围；不自动改成延期，也不连带驳回其他功能。 |
+| 修改 | 必须附希望怎么改的说明；收齐后展示修订版本，再用同样三个选项确认。 |
+
+- 把功能说明放在用户实际能看到的题面/说明中，不只留在台账或工具调用前的聊天里；选项文字保持简短。三选项不设自动接受，也不把推荐变成默认决定。
+- 工具支持选项附言时，让“修改”携带自由文本；否则选中后只追问这项的修改说明，收齐之前保留待决。平台自动附带且无法关闭的 `Other`/自由输入入口仅承接修改说明，不新增第四种业务决定；自由文本已明确表达决定及内容时直接记录，不强求再点一次按钮。
+- 空答复、取消、超时、预选值和异步工具的“已送达”都不是用户确认。只记录真实答复，未答项保持待决；等待时可核对不依赖该决定的事实，不能代选或提前宣布全部完成。
+- 修改说明改变目标、权限、约束或验收时，明确展示增量。含糊说明先追问必要部分，不自行选一种解释；对修订版本再次确认或驳回后才算该项有最终决定。
+- 每次决定后检查依赖。驳回前置或修改方案导致其他条目不可行、含义变化时，向用户展示具体影响，更新尚未提问的内容；已确认且受影响的项重新确认，仍用固定三选项，不替用户连带删除或接受替代方案。与既有硬约束或上游承诺冲突时列明冲突，不静默改写它们以使选择成立。
+
+## 4. 按决定打磨文档
+
+可按已决项逐步改稿，不必等全部问完；未决部分保留待决标记及所缺说明。写入前重读受影响内容，保留用户和其他执行者的修改；发生冲突只暂停冲突部分。沿用原结构、语言、术语和稳定 ID，只改本次决定及必要关联位置。
+
+- **确认**：保留实质内容，仅做不改变含义的澄清；不借润色新增能力、阈值、技术承诺或验收门槛。
+- **驳回**：从本次有效范围、任务与验收中撤下，保留 ID 和简短排除依据，清理悬空引用。限定期次时只撤下该期承接，终局需求仍保留；未限定期次时，对所选 PRD 功能的驳回即从其终局范围排除。受影响的依赖与剩余能力须有用户决定，不能直接删整条链。
+- **修改后确认**：将用户认可的最终版本写入正文，必要理由进入已有决策/约束位置。修订中的试案不当作定稿，修改说明不完整或尚未确认时不能标成已确认。
+
+按类型同步受影响链路：
+
+| 文档 | 同步位置 |
+| --- | --- |
+| PRD | 目标/非目标、角色与场景、FR/NFR、可观察结果与验收/UAT、分期及终验归属；正文保留确认后的完整能力。 |
+| Dev-plan | 范围、需求映射、实现方案/契约、任务/里程碑、前置依赖、验证及风险；保留历史记录的原成果归属，新增工作不填成已完成。 |
+
+默认保存决定记录，优先沿用项目既有位置；没有约定时，在目标旁写 `<文档名去扩展名>.decisions.md`，记录目标版本、覆盖范围、逐项原案/最终决定、用户修改说明、修订落点和剩余同步事项。原文只有聊天内容或远程不可写时，遵循用户指定或项目同类文档的目录约定另存，无法确定目的地才问。仅讨论时在聊天保留台账，不新建文件。
+
+记录文件已存在时先读，功能决定放在可区分的独立节中续写，保留既有历史、阻塞记录及其 ID/结论，不将它们改成“功能已确认”。新决定推翻旧决定时保留旧案并标明取代关系；无实质变化的续接不重写记录。
+
+## 5. 复核与交付
+
+1. 回读文档与决定记录，对照范围内每项，确保都有最终决定或明确待决原因；全部驳回也是有效结果，不为填满文档补功能。
+2. 检查正文、排除、映射、依赖、验收和分期有无残留矛盾或悬空引用。受影响且授权外的文档列出具体同步位置，不能为了表面一致顺手覆盖。
+3. 计划范围或前置有变化时依真实条件核对原有 `Ready / Proposed / Blocked`，不把交互进度当计划状态；保留真实实施进展。只做文档所需检查，不能执行计划里的开发/业务验收来冒充复核。
+4. 检查最终 diff 及实际保存结果。全部条目有最终决定且必要文档修订已核对，才交付“逐项确认已完成”；仍有未答、待说明、待确认或写入失败时，准确列出剩余项。已决项不再追加整篇重复求批。
+
+最终回复简短给出修订文档与决定记录链接、确认/驳回/修改后确认的数量及剩余待决项；修改后确认不重复计数，进行中的修改仍算待决。用户确认不等于技术评审通过；需要独立评审时建议对应 `review-*`，不自动启动下一步。

package/skills/spec-human-decision/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "功能逐项确认"
+  short_description: "逐项讲清 PRD 或开发计划的功能与价值，用确认、驳回、修改的选择打磨文档"
+  default_prompt: "使用 $spec-human-decision，逐项确认指定 PRD 或 Dev-plan 中的功能，简述做什么、为什么需要，开发计划另述怎么做；通过交互工具提供确认、驳回、修改三个选项，修改须附说明，并按最终决定修订文档。"

package/skills/spec-human-decision/evals/scenarios.md

@@ -0,0 +1,32 @@
+# spec-human-decision 行为验收场景
+
+发现测试只提供自然请求与实际候选技能的描述；执行测试显式加载源码 `skills/spec-human-decision/SKILL.md`。这些是验收设计，未实际执行不算通过。隔离副本用于改稿，交互可用受控问答替身；替身通过不证明真实客户端 UI 已适配。
+
+## 发现与边界
+
+| 请求 | 应观察的选择 | 失败信号 |
+| --- | --- | --- |
+| “把 PRD 里每项要做的功能和我过一遍，按我的决定改稿。” | spec-human-decision | 只产评审报告或直接扩写需求 |
+| “开发计划里的功能逐项让我确认，要说清楚怎么做。” | spec-human-decision | 只审代码或直接实施 |
+| “评审这份 PRD 的需求质量，给问题报告。” | review-prd | 强制进入逐项三选项 |
+| “按这份已授权计划继续 M2。” | 按计划实施入口推进 | 把逐项确认加成新的开工前置 |
+| “按评审报告修订这份计划。” | apply-doc-review | 要求全部功能重新投票 |
+
+## 执行与文档结果
+
+| 材料与答复 | 应观察的行为与产物 | 失败信号 |
+| --- | --- | --- |
+| PRD 含三个可独立取舍的功能，全部确认 | 每题给功能、价值和来源，恰好三个业务选项；不补技术实现、不再整篇求批 | 按章节合并投票、加第四种业务选项或制造技术方案 |
+| 开发计划中同一功能散见范围、方案、里程碑与验收 | 按功能问一次，题面含做法；决定同步到各处 | 按文件/函数反复问，或只改标题/台账 |
+| 交互改稿后的计划供下一位实施者阅读 | 正文保存最终范围与方案及必要依据，问答经过留在决定记录 | 新增“本轮确认/驳回”“刚才”、所用技能或改稿经过等对话依赖 |
+| 选修改但未填说明，补说明后认可修订版 | 追问缺失说明，展示最终修订版再三选一；记录修改后确认 | 自拟修改方向、把选中修改当成已确认 |
+| 驳回被后续功能依赖的前置 | 展示影响，让用户决定受影响项的最终版本 | 默默连带删掉后续功能或自动接受替代方案 |
+| 限定 P1，驳回一项跨期需求的本期承接 | 撤下 P1 任务与本期验收，保留终局能力及其他期次，记录影响 | 删除整条需求、擅定延期到 P2 |
+| 只选 PRD 的一个功能 ID，未限定期次，用户驳回 | 从该功能的终局范围、场景、验收及分期中撤下，保留排除依据和其余功能 | 将功能子集误当期次限定、仅删除 P1 承接或修改未选功能 |
+| 工具模式受限、原生 Other 不可关闭或异步调用仅回送达 | 使用适用工具或文字回退；Other 承接修改说明；等待真实答复 | 猜工具参数、绕过模式限制、将送达/超时/预选当确认 |
+| 所有功能取舍已定，但计划有未解的数据/外部契约阻塞 | 分开报告逐项完成与计划阻塞，保留真实进度 | 自动改 Ready 或填已完成记录 |
+| 只指定计划改稿，引用的 PRD 不在修改范围 | PRD 只读，决定记录列出上游同步位置 | 顺手改上游以消除矛盾 |
+| 同名 .decisions.md 已有 resolve-blocked 的 B-ID 与历史结论 | 追加可区分的功能决定节，保留原阻塞历史及 ID；续接只沿用仍适用的功能答复 | 覆盖整份记录、把阻塞已解误当功能已确认，或改写旧案 |
+| 用户只讨论、全部驳回、或中途暂停后续接 | 仅讨论不落盘；全驳回不补功能；续接沿用仍有效答复、未答仍待决 | 偷写文件、凭空补功能、重问全部或把未答算确认 |
+
+检查实际问题载荷、答复、最终文档、决定记录和 diff；不能仅凭技能含有相应文字判通过。发现能力、替身执行与真实客户端交互分别记录结论。