preqstation

这是 Agent 端的生命周期技能。调度器主机设置和启动编排位于独立的 PREQ CLI/OpenClaw 运行时包中。

环境

推荐的 MCP 模式：

• 注册来自 PREQSTATION projects-manager 服务的远程 MCP 端点：
  • Claude Code：claude mcp add -s user --transport http preqstation https://<your-domain>/mcp
  • Codex：codex mcp add preqstation --url https://<your-domain>/mcp
  • Gemini CLI：gemini mcp add --scope user --transport http preqstation https://<your-domain>/mcp
• 客户端首次向 /mcp 发出实际请求时，会启动 OAuth
• Codex 通常会在 add 期间触发登录，因为它会立即探测服务
• Gemini CLI 也可能在 MCP 注册期间或首次实际调用工具时提示进行身份验证。如果 gemini mcp list 仍将 preqstation 显示为 Disconnected，请打开交互式 Gemini 会话并运行 /mcp auth preqstation。
• Claude Code 通常会先保存配置，在首次使用或执行 claude mcp get preqstation 前可能显示 Needs authentication
• 建议使用一个用户级 Claude Code PREQ 注册项，避免积累重复的项目本地条目
• 使用 claude mcp list、codex mcp list 或 gemini mcp list 验证 MCP 注册
• 按照客户端提示完成浏览器登录流程

可选的 Shell 辅助模式：

• PREQSTATION_API_URL：PREQSTATION API 基础 URL（示例：https://mypreqstation.vercel.app）
• PREQSTATION_TOKEN：PREQSTATION Bearer 令牌（在 PREQSTATION /api-keys 中生成）
• PREQSTATION_ENGINE（可选）：客户端无法自动检测时使用的备用引擎（claude-code | codex | gemini-cli）

Agent 身份与引擎映射

每个 Agent 都必须标明自身身份，并在所有任务操作（列出、创建、规划、启动、更新状态、完成、审核、阻塞）中使用相应的 engine 值：

如果你是……	使用 engine=
Claude（Anthropic）	claude-code
GPT / Codex（OpenAI）	codex
Gemini（Google）	gemini-cli

列出、创建、规划、启动、完成、审核或阻塞任务时，始终包含你的 engine 值。

Gemini CLI 工作进程可以通过 gemini 交互式运行，也可以通过 gemini -p "<prompt>" 无头运行。 如果已安装的 Gemini 环境不支持远程 HTTP MCP，请改用 Shell 辅助回退方案，而不要使用此 MCP 路径。

MCP 插件模式（推荐）

如果可以使用 MCP，请优先使用 PREQSTATION 服务提供的远程 /mcp 端点。 所有变更类工具都接受可选的 engine 参数，并始终按以下顺序发送 engine 值：

1. 显式工具参数
2. 现有任务的 engine（如果可用）
3. MCP initialize.clientInfo.name 自动检测
4. PREQSTATION_ENGINE
5. 回退为 codex

工具	engine 用法
preq_list_projects	只读，无需 engine（列出 PREQ 项目，用于设置和本地仓库映射）
preq_list_project_activity	只读，无需 engine；按日期范围获取活动动态，供同步／定时任务使用，不用于任务执行生命周期
preq_list_tasks	只读，无需 engine
preq_get_task	只读，无需 engine
preq_get_project_settings	只读，无需 engine（按键获取项目部署设置）
preq_list_task_comments	只读；对于 comment 目标，在目标评论附近获取任务评论作为对话历史／参考
preq_get_task_comment	只读；在回复或更改评论状态前，获取正在处理的确切评论
preq_update_qa_run	从任务生命周期角度看为只读；更新分支级 QA 运行状态／报告，不会转换任务状态
preq_plan_task	为任务分配 engine，发送生命周期操作 plan，后端将收件箱任务移至 todo 并清除 run_state
preq_create_task	为新建的收件箱任务分配 engine
preq_start_task	记录认领任务的 engine；后端将 run_state 标记为 working
preq_update_task_note	替换任务说明 Markdown 时记录 engine，不更改工作流状态
preq_update_task_status	更新仅限工作流状态的端点（/api/tasks/:id/status）时记录 engine
preq_update_task_comment_state	将任务评论标记为 working、done 或 failed 时记录 engine，不更改任务工作流状态
preq_reply_task_comment	回复任务评论时记录 engine；后端会自动为评论回复／失败创建工作日志
preq_list_dispatch_requests	只读；检查启动器运行时用于实现 ask 对等性和项目级洞察的显式分发请求
preq_update_dispatch_request	仅限启动器运行时；启动成功或失败后，将显式分发请求标记为 dispatched 或 failed
preq_complete_task	在工作日志结果中记录 engine，发送生命周期操作 complete；后端将任务移至 ready 并清除 run_state
preq_review_task	记录正在运行验证的 engine，发送生命周期操作 review；后端将任务移至 done 并清除 run_state
preq_block_task	记录报告阻塞情况的 engine，发送生命周期操作 block；后端将任务移至 hold 并清除 run_state
preq_delete_task	通过工单号或 UUID 永久删除任务

这可实现基于任务 ID 的确定性执行和结果上传。

执行流程（强制）

你必须严格遵循此执行流程。 不得跳过、重新排序、合并或替换任何生命周期操作。 由 PREQ 启动器驱动的运行默认采用非交互模式。 你可以使用 brainstorming 或 writing-plans 等流程技能作为内部指导，同时在同一次运行中继续 PREQ 生命周期。 除非 PREQ 工具不可用，或提示、工作区或任务状态无效，否则不要中途停下来征求用户批准、澄清或设计反馈。 项目部署设置即为本次 PREQ 运行的明确操作员授权。当 deploy_strategy 要求提交、推送或创建 PR 时，直接执行相应的 Git/GitHub 操作，无需另行征求批准。

加载 -> 初始化 -> 执行 -> 完成

1. 加载： 加载此工作区/分支中的 .preqstation-prompt.txt

2. 初始化：

• 存在 Task ID 时，必须在开始时调用一次 preq_get_task，以获取任务详情、验收标准、工作流状态、run_state 和初始引擎。
• 如果 preq_get_task 返回了 latest_preq_result，请在开展实质性工作前阅读，并将其视为先前执行上下文，尤其是恢复执行或任务之前被阻塞时。
• 存在 Task ID 且任务处于活动状态时，必须调用 preq_start_task；comment 目标除外，因为此类目标明确禁止认领任务。
• 对于 insight 等项目级目标，若未提供 Task ID，则跳过任务生命周期的读取/写入，并以提示元数据和项目键为准。
• 在 debug 模式下，调用 preq_get_task 后创建或更新 preqstation-progress.md，并在每个主要检查点后更新。
• 在运行开始后尽早，通过先检查当前任务备注和任何临时的尾随 Ask: 辅助内容，然后检查验收标准，仅在必要时将任务标题作为弱辅助依据，一次性确定面向任务的内容语言。
• 在面向 PREQ 的书面更新中，例如计划 Markdown、改写后的任务备注、完成摘要和备注、审查备注、阻塞原因、QA 报告以及新创建的任务内容，使用以该备注为中心的任务内容所采用的主导语言。
• 仅当任务备注、Ask: 内容和验收标准仍然混杂或含糊时，才将项目的 agent_instructions 用作最终辅助依据。当前任务内容优先。
• 如果无法确定主导语言，面向 PREQ 的书面更新默认使用英文。
• 除非用户明确要求使用复选框，否则不要在 AI 生成的任务备注、计划 Markdown、验收标准、QA 报告、描述或新创建的任务内容中使用 Markdown 复选框任务列表语法，例如 - [ ] 或 - [x]。改写现有内容时保留用户撰写的复选框；否则使用普通项目符号或编号列表。

3. 执行用户目标 用户目标位于 .preqstation-prompt.txt 中

• 如果用户目标以 plan 开头：
  • 使用本地代码开始规划。
  • 规划仅指生成计划。你可以检查本地代码，但不得实现产品变更、运行部署步骤，或运行测试、构建、lint 等验证命令。
  • 在因缺少代码而阻塞之前，检查主检出目录和当前工作树。如果工作树处于引导仓库状态（例如仅跟踪了 .gitignore），但主检出目录包含实际应用文件，则应将其视为仓库恢复，而不是项目缺失。
  • 在引导仓库恢复期间，确保 origin 存在且与 PREQ 仓库 URL 相符。如果 origin 缺失且已知仓库 URL，则使用 git remote add origin <repo_url> 添加。
  • 在 main 上提交基线项目文件，推送到 origin/main，重新创建或刷新工作树，并在代码可供检查后继续规划。
  • 仅当主检出目录属于错误的仓库、仓库 URL 不可用或不匹配，或者向 origin/main 推送引导恢复内容失败时，才阻塞此次运行。
  • 使用计划 Markdown 和纯文本验证标准调用 preq_plan_task。除非保留用户编写的复选框，或用户明确要求使用复选框项目，否则不要将这些标准格式化为 Markdown 复选框。
  • 流程技能仅可作为内部指导。此次运行必须保持非交互，并以 preq_plan_task 结束。
• 否则，如果用户目标以 ask 开头：
  • 重写或更新现有任务备注。保持工作流状态不变。
  • 将当前任务备注及任何临时的尾随 Ask: 辅助区块作为重写的源材料。
  • 如果 ask 明确要求原型或可供审阅的产物，则允许在本地生成产物。
  • 产物发布尽力而为；但如果已有安全可用的产物提供方，则必须尝试发布。使用当前 Agent 会话中已通过身份验证的提供方；Fast.io 是受支持的提供方之一，并非唯一有效目标。
  • 如果当前 Agent 已有经过身份验证的 Fast.io MCP 会话或其他经过身份验证的提供方，则视为该提供方已可用，应尝试发布，无需等待额外提供方指示。
  • 持久化产物链接必须采用 private-or-skip 策略。经过身份验证的工作区目标、仅限成员访问的共享，以及注册账户访问均视为可接受的私有访问。跳过不会过期的“任何拥有链接的人均可访问”URL 或其他仅提供公开链接的模式。
  • 如果提供方可以创建临时外部共享或快速共享链接，则为已发布的产物创建 7 天后过期的审阅链接。使用 access=quickshare 或提供方的等效标记，并包含 expires=...；不要创建永不过期的公开链接。
  • 如果本地产物是 HTML 原型或 HTML 模型图，至少生成一张用于审阅的 PNG 截图；如果有经过身份验证的提供方可用，则尝试同时发布 HTML 源文件和截图产物。
  • 不要将产物元数据写入 Artifacts: Markdown 区块。任务备注应聚焦于持久的任务上下文。
  • 在传给 preq_update_task_note 的 artifacts 数组中记录已发布链接或跳过／本地产物信息。根据适用情况，使用包含 type、title、url、provider、access、expires、localPath、reason 以及可选 metadata 的对象。
  • 对于原型或可供审阅的产物请求，在 artifacts 中包含产物发布结果或跳过原因。如果跳过发布，则包含本地产物路径，以及简洁的 reason，例如提供方不可用、未通过身份验证或没有安全目标。
  • 将 localhost 和 127.0.0.1 URL 视为仅供本地使用的诊断信息。不要将其作为唯一的审阅链接；应发布私有产物 URL，或明确标记该产物仅限本地使用，并注明跳过原因。
  • 使用 preq_update_task_note(noteMarkdown=..., artifacts=[...]) 持久化重写后的 Markdown，并通过结构化的 artifacts 字段传入任何已发布的产物 URL 或产物发布跳过／本地记录。
  • 通过调用 preq_update_task_status 清除执行状态，并使用 preq_get_task 获取的当前工作流状态。
  • 最终保存的备注不得包含临时的 Ask: 辅助区块。
• 否则，如果用户目标以 comment 开头：
  • 仅处理引用的任务评论；整个运行期间保持任务工作流状态不变。
  • 将评论视为对话请求渠道，而非实施的事实依据。只有当本评论目标明确要求通过 preq_update_task_note 将其纳入任务备注／规格时，评论才会影响后续实施。
  • 必须在开始时调用 preq_get_task、preq_get_task_comment 和 preq_list_task_comments，以获取任务详情、当前备注、工作流状态、现有运行状态、正在处理的确切评论，以及该任务范围内的相关评论对话。
  • 将引用的 comment_id 视为此次运行的主要请求。其他用户、Agent 和系统评论仅作为对话历史／参考，包括先前的 AI 回复；应利用它们理解对话进展并避免给出矛盾或脱离上下文的回复。
  • 不得将非目标评论视为独立的可执行要求。只有当前目标评论明确或无歧义地要求通过 preq_update_task_note 将对话决定纳入任务备注／规格后，这些评论才会影响后续实施。
  • 禁止调用 preq_start_task；评论使用评论状态，而非任务 run_state 声明。
  • 在开展实质性工作之前，使用 preq_update_task_comment_state 将原评论标记为 working。
  • 在决定如何回复之前，检查当前任务备注、目标评论和评论历史。
  • 仅当评论明确要求更改备注、计划或规格时，才可选择调用 preq_update_task_note。这是唯一一种“将评论纳入备注”的方式：将请求的变更转化为规范的备注／规格语言，然后在回复中说明备注已更新。对于普通答复、确认或实施审阅评论，不要重写备注。
  • 使用 preq_reply_task_comment 回复，并准确设置 noteUpdated，表明是否调用了 preq_update_task_note。
  • 成功回复后，使用 preq_update_task_comment_state 将原评论标记为 done。
  • 处理评论目标时，绝不要调用 preq_complete_task、preq_review_task、preq_plan_task 或 preq_block_task。
  • 发生失败时，保持任务工作流状态不变；如果可行，使用 preq_reply_task_comment 回复失败详情，然后使用 preq_update_task_comment_state 将原评论标记为 failed。如果无法回复，仍应将评论标记为 failed，并提供最具体的失败原因。
  • 不要为评论处理创建单独的工作日志。后端会自动为评论回复和失败更新创建工作日志。
• 否则，如果用户目标以 insight 开头：
  • 此分支可以没有任务 ID。不要臆造任务 ID；不存在任务时，不要调用任务生命周期变更操作。
  • 从当前工作树检查本地项目，并仅将提供的 Insight Prompt 用作任务生成指导。
  • 在创建任何内容之前，使用当前 projectKey 和 detail=full 调用 preq_list_tasks，以避免在 inbox、todo、hold 和 ready 中创建重复任务。
  • 使用 preq_create_task 创建多个 Inbox 任务。
  • 为每个创建的任务指定一个简短且共同的主题前缀，该前缀应源自用户意图或当前工作区域。
  • 保持 description 详尽，但 acceptanceCriteria 应为纯文本验证标准，不使用 Markdown 复选框语法。
  • 不要变更现有任务，也不要用长篇实施计划取代任务创建。
• 否则，如果用户目标以 qa 开头：
  • 此分支可以没有任务 ID。不要臆造任务 ID；不存在任务时，不要调用任务生命周期变更操作。
  • 从 .preqstation-prompt.txt 解析 qa_run_id，并在本地目标 URL 已知后立即使用 preq_update_qa_run 将运行状态标记为 running。
  • 如果 .preqstation-prompt.txt 中包含 qa_task_keys，则在浏览器测试之前，对每个任务键调用 preq_get_task，并将这些任务的标题、描述和验收标准作为 QA 范围。
  • 如果当前 Agent 可访问 dogfood 技能，则将其作为浏览器测试和报告生成的默认 QA 工作流。
  • 从当前工作树／分支启动当前项目，确定本地目标 URL，并针对该 URL 运行浏览器 QA。
  • 将 QA 限定在指定的 Ready 任务，以及抵达并验证这些任务所需的最少导航或健全性检查。不要扩展为与任务无关的全面应用探索式 QA。仅当无关问题阻碍范围内的验证或导致应用无法启动时，才报告这些问题。
  • QA 报告可包含截图、视频和文档的可选产物引用。存在安全可用的提供方时，采用相同的 private-or-skip 策略。
  • 如果生成本地产物后跳过了 QA 产物发布，则应在结构化的 artifacts 数组中记录发布结果或跳过原因，而不是写入 Markdown 报告正文。
  • QA 结束时，再次调用 preq_update_qa_run，并传入最终状态（passed 或 failed）、target_url、Markdown 报告、汇总计数，以及在生成产物时传入 artifacts=[...]。
  • 除非此次运行也在处理真实的 PREQ 任务，否则不要调用 preq_complete_task、preq_review_task 或 preq_block_task。
• 否则，如果用户目标以 implement 或 resume 开头：
  • 实施代码变更并运行任务级测试。
  • 以任务备注、验收标准和明确的 PREQ 结果上下文作为实施的事实依据。不要获取或解读任务评论，将其视为隐藏要求或对话上下文；评论只有在先前的评论目标已更新规范任务备注／规格后，才会影响实施。
  • 如果存在 latest_preq_result，则使用它了解最新的阻塞原因、先前摘要和最近的 PREQ 执行上下文，然后再进行变更。
  • 根据 Deployment Strategy Contract 确定部署策略。
  • 执行 direct_commit、feature_branch 或 none 所需的 git／部署步骤。遵循 Deployment Strategy Contract 一节。
  • 不要在运行中暂停以等待用户批准，也不要进入单独的对话式设计／规格讨论流程。
• 否则，如果用户目标以 review 开头：
  • 运行验证（tests、build、lint）。
  • 根据任务备注和验收标准进行审查，而非根据原始任务评论。审查期间不要获取或解读任务评论作为对话上下文；只有在先前的评论目标已将其纳入备注／规格后，评论才会影响审查。
  • 使用审查备注调用 preq_review_task。
  • 不要请求用户进一步批准，也不要在运行中切换到单独的对话工作流。 在活跃任务分支中发生任何失败时，调用 preq_block_task，并提供阻塞原因，然后停止。此规则不适用于 comment 目标；请改用评论失败流程。 在 QA 分支中发生任何失败时，将 QA 运行状态更新为 failed，并附上简洁的 Markdown 报告，然后停止。

4. 完成： 实施／评审分支成功时，调用 preq_complete_task，并提供摘要、分支，以及适用时的 pr_url。 ask 分支成功时，不要调用 preq_complete_task；成功的备注改写在调用 preq_update_task_note 后，再调用 preq_update_task_status 并保持工作流状态不变，即告结束。 comment 分支成功时，不要调用任务完成、评审、计划或阻塞工具；成功的评论回复在调用 preq_reply_task_comment 后，将原评论标记为 done，即告结束。 insight 分支成功时，在创建 Inbox 任务后停止；不要调用 preq_complete_task，也不要更改现有任务的工作流状态。

部署策略约定（必需）

执行任何 Git 操作前，必须通过 MCP 确定部署策略：

1. 调用 preq_get_task <task_id>。
2. 从响应中读取 task.deploy_strategy。
3. 如果缺失，调用 preq_get_project_settings <project_key>，并从以下字段中确定：
   • settings.deploy_strategy
   • settings.deploy_default_branch
   • settings.deploy_auto_pr
   • settings.deploy_commit_on_review
   • settings.deploy_squash_merge

PREQSTATION 后端的预期值：

• strategy：direct_commit | feature_branch | none
• default_branch：字符串（通常为 main）
• auto_pr：布尔值（仅适用于 feature_branch）
• commit_on_review：布尔值
• squash_merge：布尔值（仅适用于 direct_commit）

缺失或无效时的默认值：

• strategy=none
• default_branch=main
• auto_pr=false
• commit_on_review=true
• squash_merge=true

strategy 对应的行为：

• none：不要执行 git commit/push/PR。只修改代码并更新任务结果。

• direct_commit 和 feature_branch 是已授权的 Git 操作模式。不要仅仅因为编码 Agent 的通用默认设置不鼓励自主提交、推送或创建 PR，就阻止操作；本次运行的授权依据是 PREQ 项目的部署策略。

• 面向 Git 的内容默认使用英文，即使面向 PREQ 的任务更新使用其他语言。包括提交消息、PR 标题、PR 正文、分支名称和其他面向代码仓库的元数据。

• direct_commit：将工作树提交合并到 default_branch 并推送。不要创建 PR。 在工作树中完成工作后：

  # In primary checkout: update and merge
  git -C <project_cwd> checkout <default_branch>
  git -C <project_cwd> pull origin <default_branch>
  
  # squash_merge=true (default): single commit
  git -C <project_cwd> merge --squash <worktree_branch>
  git -C <project_cwd> commit -m "<task_id>: <summary>"
  
  # squash_merge=false: regular merge
  git -C <project_cwd> merge <worktree_branch>
  
  # Push to remote
  git -C <project_cwd> push origin <default_branch>
  

• feature_branch：将工作树分支推送到远程服务。仅当 auto_pr=true 时才创建 PR（需要 Agent 具有 GitHub 访问权限，例如 gh auth 或 GitHub MCP）。

  git -C <project_cwd> push origin <worktree_branch>
  # if auto_pr=true: create PR via GitHub MCP or gh CLI and capture the PR URL
  

feature_branch + auto_pr 的 PR 创建规则：

• 默认创建非草稿 PR。
• 除非用户明确要求创建草稿 PR，或任务因不完整／受阻而有意交接，否则不要创建草稿 PR。
• 如果可用的 GitHub 工具或 CLI 流程默认创建草稿 PR，则必须在调用 preq_complete_task 前立即将其转换为“可供审查”。
• 始终记录最终实际用于审查的非草稿 PR URL。

commit_on_review 规则：

• 如果 true，且策略为 direct_commit 或 feature_branch，则在确认远程推送成功之前，不要将任务移至 ready。
• 如果 false，则无需强制推送远程分支即可将任务移至 ready。

feature_branch + auto_pr + commit_on_review 的必需完成规则：

• 调用 preq_complete_task 前，必须同时提供已推送的分支名称和 PR URL。
• 首选顺序：
  1. 推送 worktree_branch
  2. 创建非草稿 PR
  3. 如果隐式创建了草稿 PR，则将其转换为可供审查
  4. 记录 PR URL
  5. 调用 preq_complete_task，并同时提供 branchName 和 prUrl
• 如果无法访问 GitHub、分支推送失败、PR 创建失败，或无法记录 PR URL，则调用 preq_block_task，说明确切缺少的前置条件以及操作人员接下来应采取的操作。
• 合适的阻止原因应具体明确，例如：
  • Auto PR required before ready, but gh is not authenticated on the coding agent. Run gh auth login or configure GitHub MCP, then resume.
  • Auto PR required before ready, but gh pr create failed after pushing task/proj-123/example. Fix the GitHub error and resume.
  • Auto PR required before ready, but the PR is still a draft. Mark it ready for review, capture the final PR URL, then resume.

Shell Helper 模式（可选）

如果 MCP 不可用，请加载 scripts/preqstation-api.sh，并使用 docs/shell-helper-mode.md 中说明的 Shell 辅助函数。 让 SKILL.md 聚焦于生命周期规则；函数签名和 jq／curl 说明请参阅辅助函数参考文档。

调试进度模式（可选）

仅在调用方明确请求 debug 模式或要求查看进度时使用。

• 文件路径：<worktree>/preqstation-progress.md
• 用途：为当前运行创建本地、人类可读的进度记录
• 范围：仅限当前运行；每次运行开始时刷新，不要无限追加历史记录
• 安全性：不要将其用作生命周期的事实来源；除非用户明确要求，否则不要提交或推送它

写下当前的执行流程步骤

例如：

# PREQ Progress

- Task: PROJ-123
- Objective: implement
- Status: todo
- Run State: working
- Current Step: running task-level tests
- Last Updated: 2026-03-13T14:30:00Z

## Timeline

- 2026-03-13T14:10:00Z fetched task details using `preq_get_task`
- 2026-03-13T14:11:00Z called preq_start_task using `preq_start_task`
- 2026-03-13T14:18:00Z finished local code inspection
- 2026-03-13T14:30:00Z running task-level tests
  ...