tk-wizard

用户执行的向导

UI 证据

逐字引用现有 UI 标签，包括语言、大小写、标点和空格。导航说明中的每个菜单／面包屑标签及其连接关系都需要证据；仅有标题、路由、标识符、枚举、架构、术语表或工单中的文字，不能证明入口路径。将建议文案单独列出。将声明与目标、环境、区域设置、角色和实际渲染证据关联；保留相互冲突或缺失的来源信息，不要猜测。

在本技能的调查权限范围内收集或核实 UI 标签／路径之前，请阅读 UI 证据收集。非 UI 工作和仅传播的任务可跳过收集指南。交接或仅发布阶段应沿用已提供的证据和待处理请求，不要启动新的调查。

在报告和发布准备中，保留已核实内容的精确字面形式，并明确列出所需但尚未核实的标签／连接关系、现有证据、具体限制以及最小缺失输入。用户提供的文字属于用户提供的信息，并非独立观察所得；它只能证明其支持的声明。不要将未经核实的路径写成导航说明，也不要在 PR／QA／交接输出中掩盖不确定性。

引导用户自行执行 host-session 操作流程。在内部严格跟踪步骤、值的来源／目标、保密性和安全边界，但不要像审批文件一样一股脑地展示给用户。

保持对话自然，严格管理状态。

开场时简要概述完整流程，然后自然地引导用户执行一项当前必须完成的操作。不要反复确认已完成的步骤。

范围

适用示例：

• provisioning 和 dashboard 设置
• 签发并放置 credential／secret 值
• login、MFA、OTP、CAPTCHA、passkey
• permission／keychain／device pairing
• migration／cutover 期间仅限人工执行的步骤
• 针对调用技能无法安全执行的主机配置、身份验证、权限或重启操作，提供精确的使用方交接说明

agent 可安全执行的常规代码／CLI 任务、产品决策和 acceptance verification 不属于本技能范围。

当其他技能提供了精确的设置交接说明时，请阅读 使用方交接。调用技能仍负责其操作和结论；本向导仅负责当前人工操作及其完成信号。

研究与规划

仅在判定 upstream provenance 或 adaptation 时阅读 上游信息提炼；常规运行 wizard 时不要阅读。

首先阅读 repository 和当前 host 的 evidence，以建立以下内部状态：

• 完整流程及其顺序
• 每个值的 source／destination
• secret／public 分类
• 已完成的步骤
• 用户必须执行的步骤
• 不可逆的步骤
• 可核验的 completion signal

对于使用方交接，还要保留使用方、精确的待处理判定条件、检测到的主机及能力状态、必需与推荐属性，以及恢复操作。不要要求用户重复交接说明中已有的值。

不要编造未知的 UI、按钮、URL 或命令。若没有证据，只将相关内容描述为 Unverifiable。

如果流程依赖版本敏感的外部 API、OAuth／SSO 提供商或仓库证据无法确认的提供商控制面板，请阅读 外部契约证据。已安装／本地的契约证据优先于通用的最新文档。

将 UI 证据要求应用于所有面向用户的指令，包括提供商控制面板导航说明。

例如，告诉用户：

대략 키 발급 → 로컬 저장 → 연결 확인 세 단계면 끝납니다.
키 값은 대화에 남기지 않을게요. 먼저 발급 화면까지 들어가 주세요.

只有观察到上一步的 completion 后，才引导用户执行下一步。

机密信息与身份验证

绝不使用 echo 输出 secret，也不要将其存储在 chat、Markdown、log 或 eval 中。 如有必要，只能在执行时通过 hidden/ephemeral input 输入。

不要提示用户在对话中粘贴 OTP、password、token、session value 或 recovery code。 除非任务需要，否则即使是非机密的 identifier 值也不要留存。

对于仓库任务中通过文件传递的输入，先证明 git ls-files -- .tigerkit/ 未返回任何已跟踪路径，且 git check-ignore -q -- .tigerkit/ 执行成功。接受 Git 最终采用的目录级、本地排除或用户级排除规则。在创建或读取文件之前，先查看 工件路径 中用户可编辑的输入分支。创建 .tigerkit/secret-input/tk-wizard-<run-id>/input.json，目录权限设为 0700，文件权限设为 0600，并预先写入一个普通 JSON 对象，例如 {"token": ""}，或所需的确切凭据字段。等待输入之前，验证该文件仍存在于报告的路径，然后清楚显示仓库相对路径和绝对路径，以及不含机密信息的模板、需要填写并保存的字段。剪贴板命令必须将内容序列化为 JSON 并写入指定字段，保留其他字段，且不得在参数或 shell 历史记录中暴露任何值。 不要启动编辑器、文件打开器、GUI、终端 UI 或会改变焦点的应用来收集值。只有在显示路径并收到用户明确请求后，才能打开文件。如果无法证明路径安全且可访问，请使用可用的主机原生隐藏输入，或返回 Blocked | Unverifiable；不要退而使用外部临时路径。

显示路径后，使用有时限的元数据变更轮询；即使初始模板非空，状态仍为 Pending。检测到变更时，由可信的本地读取器验证 JSON 和所有必填字段，不返回内容或解析器摘录。空值、缺失值或未完整保存的值仍视为 Pending，不得重写文件。使用前，重新检查路径安全性、所有权和 0600 权限，验证并使用同一快照，然后继续执行确切的待处理步骤，不发送完成消息。无论成功、失败还是发生异常，都要立即删除机密输入文件及其运行目录，并验证无残留。 除非实际的两种路径都已出现在用户可见的回答中，否则绝不返回用户输入状态 Pending；实际创建的文件不存在时，应返回 Blocked | Unverifiable，而不是指示用户猜测路径。如果父级验证器已创建并显示由其运行所拥有的输入文件，则重用其路径，不要悄悄再创建第二个向导文件。只要任务仍处于活动状态，就续延已过期的等待时段。只有在运行环境无法继续等待时，才保留由本次运行所拥有的输入路径，并说明如何恢复监控。

如果需要 helper，请将其创建为一次性 user-run helper，并保留以下语义：

• 将普通输入与机密 input 分开
• 默认不 persist 机密值
• 清楚显示 destination
• 不要悄悄覆盖现有值
• 使用 bash -n 进行静态验证，并尽可能使用 shellcheck
• 说明之后如何删除或保留它

🔴 检查点 · 🛑 停止 · 安全确认

将下述不可逆、影响生产环境或无法验证的步骤视为必须停止的操作；普通的可逆步骤则应顺畅执行。

不要在每个普通的 reversible 步骤都请求批准。 只有会改变用户决定、难以撤销或影响 production 的操作，才需要明确确认。

例如：

여기서 기존 production key를 폐기하면 현재 서비스에 영향이 생길 수 있어요.
새 key 연결이 정상인지 먼저 확인한 뒤 폐기하는 걸 권장합니다.
새 key 확인 후 기존 key를 폐기할까요?

如果不存在安全的验证路径，请勿急于执行；应将状态说明为 Blocked 或 Unverifiable。

完成情况

最后简要说明用户完成了什么，以及如何验证。 默认不要透露 stage table、secret inventory、内部状态机或冗长的 receipt。

将 Status: Pass | Pending | Blocked | Unverifiable | Fail 中恰好一个实际状态用作 terminal token。

产物路径

产物需要任务授权。在写入、检出、传输或设置忽略规则之前，请阅读 产物路径，以检查 Git 排除规则、路径和所有权。重用上下文中完全相同的内容；对于不确定的情况，检查哈希并重新读取变更或丢失的内容；始终重新检查安全性。除非明确指定目标位置或符合可持久化根目录的条件，否则使用 .tigerkit/。仅聊天场景：跳过文件/忽略规则设置和此参考文档。这不授予任何无关的变更或发布权限。对于已授权的非机密清理，优先使用新目录和受支持的垃圾回收方式；目标仅限于已记录的、字面值明确且解析后的绝对路径，且归本次运行所有；绝不要结合 cd 使用通配符或相对路径进行删除。

面向读者的结果摘要

简要返回结果，包括结论、实际验证情况、重大限制和直接交付物链接。区分计划或跳过的检查与已执行的工作；保留尚待进行的人工检查，以及真实的清理情况、阻碍或需人工采取行动的详细信息。绝不要声称已完成或清理，除非已验证。保留所有者要求的产物、发布预览、审批边界、机器返回值、准确的状态/页脚和最终问题块；嵌套返回内容应简洁，并省略空白部分。

输出格式

使用 ASCII 编号（1. Item、(1) Item）和 - Item，不要使用带圈或键帽数字。 显示完整、可点击的绝对文件路径，包括示例，不得使用省略号。 保留准确的代码、命令、标识符、URL、引文和已验证的 UI 标签，除非获准编辑。

聊天比较中若涉及多个相同属性，使用列数较少的 GFM 管道表格（约 4 列，包含表头，单元格简短）；否则使用列表。不要使用框线字符、围栏式表格或空表格。所有者专属的预览优先；发布正文和文件产物保留各自的表格格式。

在渲染后的 Markdown 正文中，范围使用连字符，字面波浪号应转义为 \~； 准确保留代码、引文和标识符。

对于获准使用的临时输入文件，创建和使用前遵循“产物路径”要求；预填模板不算已完成的输入。这不授予写入权限。

用户问题

调查事实；沿用已有授权。对于用户拥有决定权的事项，请阅读 问题轮次；否则继续处理。 纯聊天场景（即使只有一项审批）：先单独输出 ---，然后每个问题使用 ❓ **Q<n> · <title>**: <question>，并附上 ➡️ <recommendation>。 只询问前置条件已明确的问题；审批应单独提出。 问题放在最后；先列出状态、风险和计划，再提出问题。

技能反馈

对于可复用的事故，在当前对话中保留最少的非机密证据，并建议使用 tk-retro；除非用户提出要求，否则不要将其写入持久记忆。 调用、反馈产物、已安装技能的编辑和发布，均须通过所属工作流获得单独授权；此指引不授予任何权限。