SuperAPI AI 工具集

linear-refine

智能体与模型

查看项目

更新于 10-16 00:01

技能介绍

用途:把 Linear 议题细化为可实施的计划。工作流以仓库根目录为来源,需阅读并遵循 agents/questioner.md、docs/questioner.md、docs/agent-required-passes.md、docs/superpowers-linear-persistence.md、templates/linear-plan-comment.md 与 schemas/linear-ai.plan.v1.schema.yaml。

主要能力:一次只问一个问题;在标记计划为 ready 前执行必需的本地审查/拷问环节;通过标记的计划评论记录结果;支持子代理中继模式与非技术录入交接。

认领锁:遵循 docs/workflow.md 的 Claim Lock Rule。开始时重读议题,若已带 in-use 且本次并非恢复自身认领,则停止并报告该议题已被认领且不做修改;否则认领时添加 in-use 标签。停止处理时(ready 交接、blocked 或放弃)移除 in-use。in-use 在 llm-* 命名空间之外,需显式释放。认领时还要把 linear-ai:claim 块写入议题描述(templates/linear-claim-block.md),含 claimed_by: linear-refine 与 ISO 8601 的 claimed_at,并保留其他描述内容;释放时移除该块。

问卷启动:写 ready 计划前,依据议题、评论、链接文档与代码库检查等来源证据判断是否需要问卷。若无实质歧义,记录无需问卷并继续。实质歧义指产品行为、UX、范围或数据语义在合理选项间可能不同的分支;存在多个合理选项的修复设计选择始终算实质歧义,即使代码证据偏向其一,也应给出证据与推荐答案而非直接决定。仅纯机械选择(命名、文件位置、复制既有相同模式)可不问,并在 do_not_assume 记录被拒备选。来源证据用尽后仍有实质歧义,则启动真实问卷/访谈路径;可用 grill-me 或 grill-with-docs,但不要求安装,不可用时直接回退:只问一个具体问题,附推荐答案,等待用户回复,再更新计划草稿后问下一个。在问卷证据显示每个实质歧义已答复或被明确接受为未知前,不得标记 plan_status: ready。

子代理中继模式:作为批量子代理且无直接人工通道时,访谈要求不豁免。每轮问题发给调度编排器并等待转达答案,暂停期间保持 in-use 认领。实质问题未答复且操作者未明确接受时,绝不设 plan_status: ready。

非技术录入交接:若议题带 nontechnical-intake,视为需先做技术翻译的通俗录入。写 ready 计划前:保留原始通俗报告;阅读 Technical triage gaps 部分;从议题、评论、链接文档、Linear 上下文与仓库证据识别受影响系统;把期望成功转为可测试验收标准;用技术发现替换或补全 Technical triage gaps;无法从现有证据解决的未知保持显式。剩余未知未解决或未明确接受前不得标记 ready。技术分诊完成后,用 save_issue 移除 nontechnical-intake 并应用常规细化标签转换;若 Linear 写入不可用,把移除 nontechnical-intake 列入 REQUIRED_LINEAR_MUTATIONS。

拷问延续:就计划的每个实质分支持续访谈,直到达成共识。一次走一个决策,解决决策间依赖,并为每个问题给出推荐答案。一次只问一个问题;若问题可通过议题、评论、链接文档或代码库回答,则去探索而非提问。每次人工答复后,复述已接受决策,更新计划草稿或 Linear 评论,并问该分支是否还有补充。有则继续当前步骤问下一个聚焦问题;无且分支已解决,则进入下一分支或建议进入下一工作流步骤。每个实质分支拷问完成或人工明确接受剩余未知前,不得标记 ready。

Linear MCP 契约:可用时使用 get_issue 读取当前议题字段、标签、状态与分支元数据;list_comments 在创建新修订前读取已有标记计划/状态评论;save_comment 发布标记计划评论或回复相关线程;save_issue 应用 llm-ready、移除其他 llm-* 标签、开始时添加 in-use 认领并在停止时移除,写入可用时更新状态。用 scripts/validate_marked_comments.ts <plan-comment-file> 校验标记计划评论;若有 Linear 元数据快照,用 scripts/validate_marked_comments.ts --metadata <metadata.json> <plan-comment-file> 校验标签。使用代理可用的本地 JavaScript 包管理器或运行时:Bun 可直接运行 .ts 脚本;Node/npm/pnpm/yarn 环境应通过 tsx 等 TypeScript 运行器执行。若 Linear MCP 写入工具不可用,不要声称已更新标签、状态或评论,而应发出 REQUIRED_LINEAR_MUTATIONS,含确切评论正文与标签/状态变更。

步骤完成交接:细化完成草稿、blocked 或 ready 计划修订时,报告变更内容、校验/写入证据、当前 Linear 标签/状态与建议下一步。询问本细化步骤是否还有补充;有则继续并更新计划,无则建议进入下一工作流步骤,通常在有 llm-ready 时进入 linear-implement,仍有歧义时进入另一拷问分支。在“是否还有补充”回答为否后,询问用户是否继续推荐的下一个技能,明确点名并等待确认,不要自动运行。响应结构:当前阶段、变更内容、证据、缺失证据、未决阻塞、建议下一步、建议下一技能,以及两个问题:继续前是否还有补充?是否继续推荐的下一个技能?当最新标记计划评论为 plan_status: ready、标签/状态变更已应用或已发出、且无未接受的阻塞问题时停止。