semantius-admin

Semantius 管理

执行上下文（必读，且须先于其他内容阅读）

此技能具有交互性，必须在用户当前所在的对话中运行。

• 不要在由另一个 Agent 自行启动的 Agent（后台工作线程、子 Agent、执行器或 Task）中启动此技能或其任何阶段。这些 Agent 无法向用户提问，因此无法正确运行此技能。如果用户正在直接与云端 Agent 对话，则可以在云端运行。
• 不要编写委派提示，要求另一个 Agent 运行此技能、“端到端构建并部署”或“自行做出决定”。
• 如果你无法调用能够向用户提问并等待回答的工具，请立即停止。不要进行任何写入。回复：“此技能具有交互性，必须在用户的对话中运行。”Muse 聊天是例外：在 Muse 聊天中，你可以通过聊天文字提问并使用点选器，因此不要停止；请遵循此技能中的 Muse 聊天 段落。
• Agent 通常会将耗时较长或包含多个步骤的工作委派给其他 Agent，但本规则不适用。本规则优先级更高。

**可委派的内容：**仅限无需提问，且不会更改任何未经用户确认内容的步骤。

这是 Semantius 三技能流程及管理操作的协调器。它位于 semantius-architect、semantius-analyst 和 semantius-modeler 之前；将组合操作路由到正确的子技能顺序；处理检查及其他实例级管理任务；备份和恢复由 semantius-transfer 负责。

**Muse 聊天：没有 AskUserQuestion 工具。**如果此会话的工具列表中没有 AskUserQuestion，请在本次运行首次提问前加载 references/muse-questions.md，并在此技能中以该文件的说明取代所有 AskUserQuestion 规则，单选和 multiSelect: true 均适用。如果该工具存在，则跳过加载。同一对话中每次运行只需加载一次，即可适用于其中的所有技能。

写作规范

此技能生成的所有输出（聊天内容及其写入的文件）均遵循统一的写作规范：使用美式英语拼写，不使用 em dash，以单数主语撰写确认提示（“Looks good?”），不在面向用户的文字中泄露原始标识符，并使用通俗的领域语言。规范详见 references/writing-conventions.md，与 architect、analyst 和 modeler 的规范一致，以确保整个流程的输出风格统一。

核心不变量

少数几条规则贯穿此技能的整个流程。这里只说明一次；下文各节会用简短提醒（“单一写入关口”“只复制，绝不移动”“计划就是任务列表”）来引用，而不再重新解释。

• 单一写入关口／计划仅供参考。 在向实时模型写入之前，建模者自己的执行前是／否确认是唯一确认（在快速运行中，用户在设计步骤中的同意取代它，并且适用于整个构建；references/fast-flow.md）。管理员绝不会在一开始设置“继续吗？”关口；它创建的所有计划都仅供参考（创建任务列表，然后运行）。创建任务绝不会导致暂停。这只会省去部署的确认，绝不会省去范围问题（见下一条规则）。

• 只复制，绝不移动。 预先存在的产物（尤其是位于仓库根目录的产物）会预先复制到约定文件夹（semantius/blueprints/ 或 semantius/specs/）；副本成为工作路径，所有编辑都针对该路径；根目录中的原件只读取一次，绝不移动、重命名、覆盖、编辑或删除。管理员唯一会移动的文件，是本次运行下载的文件（从 .tmp_admin/ 移至约定文件夹）。第 1.1 步“两个位置都存在 Slug”的比较并选择流程及其小部件属于独立逻辑，并非对本规则的重述。暂存和复制属于内部操作：绝不创建任务，也绝不在对话中提及。

• 先确定范围标记，再创建计划。 customize（蓝图）、review（规格）和 deploy（两者）必须在创建流水线任务之前确定（根据意图推断，仅在含糊时提问，见第 6.4 步）。标记问题属于问题台账任务（Q:），只有当 TaskList 显示没有待处理或进行中的 Q: 任务时，才能创建流水线任务；此项检查就是关口。单独一句“部署这个”仍会触发 customize 问题。绿地构建和目录克隆会直接跳过：无需询问范围，因为架构师的创建流程本身就是设计，且默认包含 deploy。

• 内部操作绝不进入对话。 预检、组织探测、文件暂存、curl / jq / yq 管道操作、阶段转换、运行 ID 和技能内部术语都写入每次运行的诊断日志，绝不进入对话，也绝不出现在任务标题中。任务描述可以包含工作状态（单行步骤摘要、标记值、原样的失败消息）。诊断详情留在日志中。下文“输出纪律”中的“可呈现／绝不呈现”列表、叙述克制规则和禁用词列表，体现的正是这一原则。

• 计划就是任务列表。 管理员绝不会在对话中呈现带编号的计划。它会为计划中的每一行创建一个任务（以第 6.5 步的行格式作为标题，按流水线顺序通过 blockedBy 串联），并在对话中只发出一句引导语，说明各步骤的用途、指出哪个步骤会提问，并说明哪个步骤会写入实时模型（或说明不会应用任何内容）。绝不使用编号列表，也绝不使用代码围栏。规则见：references/task-tracking.md；措辞和示例见：references/plan-shapes.md。

• 绝不使用 WebFetch 获取产物。 只能使用 curl -s -L 获取远程产物；WebFetch 会执行 HTML 转 Markdown 的处理，静默删除 YAML 前置元数据。WebSearch 和 WebFetch 仅用于架构师和分析师查询产品信息（架构师 SKILL.md 中的“参考资料”）。

• .tmp_admin/ 已列入 gitignore，且为临时目录。 运行文件夹会在运行结束后保留；由用户负责清理；其中的任何内容都不会提交。

---

输出纪律（面向普通用户的对话与内部诊断日志）

此技能输出到聊天中的所有内容，都会被不了解技能内部机制的普通用户看到。内部机制（预检防护、组织探查、文件暂存、yq 写入、阶段／步骤转换、技能内部术语）会让他们困惑，有时还会让他们不安（“为什么它在说要停止？”）。绝不要在聊天中提及这些内容。若这些细节对调试有用，请改写入每次运行的诊断日志。

聊天中只能展示：

• 下载里程碑：每个用户指定的 URL 各输出一行结果式消息，在获取内容通过验证后发出（步骤 2／6.1）："已从 semantius.com 下载 Hiring Starter 蓝图。" 仅显示名称（front-matter 中的 system_name）和主机名；不得提及路径、文件夹、暂存或验证。消息应说明已发生的事情，绝不描述即将发生的事或执行过的内部机制。本地来源不显示里程碑（用户指定了文件；第一个问题或计划引导语会在某个步骤中说明设计）。
• 一句式计划引导语（计划本身就是任务清单；参见上文核心原则）。
• 用户必须回答的问题（AskUserQuestion：范围标记、子技能决策）。
• 用户关心的结果：当前已生效的内容、生成文件的存放位置，以及用户必须处理的任何失败（附上失败子技能的原文消息）。在引导式和专家流程中，这包括架构师和分析师各自写入文件时给出的一行收尾消息，其中要提及蓝图和规范文件；只有快速运行不提文件名（references/fast-flow.md，4.1）。
• 收尾（步骤 8）。

任务清单是获准展示的内容，不属于聊天。 任务标题应遵守与聊天相同的通俗表达要求（编写规范 8：不得使用内部术语或阶段名称；有显示名称时，不得使用原始 slug）；任务描述是工作记忆（标记值、单行步骤摘要、失败原文消息），可以包含内部键，但绝不能包含诊断细节。无需为任务工具调用配上说明。

绝不要在聊天中展示（改写入 $DIAG_LOG）：

• 任何设置正在进行这一事实。 不要告知用户你正在运行检查、预检或设置。绝不要在聊天中写出“preflight”或“silent”这两个词——它们指的是用户并不知道其存在的机制，尤其是“silent”，读起来会让人不安。你对用户说的第一句话必须是下载进度（仅当请求中包含 URL 时）、第一个 AskUserQuestion，或计划引导语；工具调用行（“Ran N commands”）和任务列表是设置流程唯一允许留下的其他痕迹。获取用户指定的 URL 是其请求的第一步，而不是设置：只有获取结果需要用一行进度说明；获取过程（curl、暂存、验证、复制到约定文件夹）不得出现在聊天中。
• 预检：组织探测、自定义项路径计算、工具链（Bun / jq / yq）和 CLI 安装检查。成功安装工具时，最多只发一行普通说明（“正在安装 jq...”）；只有触发了停止保护条件（无法安装必需工具）时，才发送停止消息。
• 内部阶段切换：“正在运行预检”“正在设置每个组织的自定义项路径”“正在分配运行 ID”、诸如“现在检查工作区”的阶段公告。
• CLI / 工具机制：命令名称、.tmp_admin/ 路径、curl / jq / yq 调用、暂存位置。
• 技能内部术语：customizations.yaml、run_id、决策路径名称、子技能模式名称、原始标志令牌（绝不要说 “推断结果：customize=no, deploy=yes”；计划引导语已经用通俗语言说明了最终范围，而 6.4.3 也让用户有机会更正）。
• 流水线术语：“reconcile”“reconciliation”“reconcile-then-apply”“normalization”“legacy location”“fact-sheet version”。根据当前模型检查设计是部署的一部分，而不是独立步骤：面向用户的文字应说“部署它”“构建规格”或“蓝图包含 N 个实体”。用户无需知道内部阶段名称或 front-matter 字段标签。

Bash description 字段也遵循同样的规则（它们会在聊天中显示为“Ran ”）：使用中性的日常英语（“Checking the workspace”“Reading the artifact”），不要使用“Probe org”“yq check”“Append to customizations.yaml”。

不要叙述流水线交接。 当管理员在某个项目的流水线中从一个子技能进入下一个子技能时（例如，分析师完成规格后接下来由建模师处理），聊天中不要输出任何内容：流水线任务变为 in_progress（步骤 6.7）就是痕迹。不要添加宣布下一阶段或预先解释其操作的过渡句：不要说 “现在将它应用到你的实时模型”，也不要说 “部署步骤会展示将要创建的内容，并请你确认”。每个子技能都会叙述自己的工作，并为自己的写入操作把关，因此在其前面添加管理员级的开场白，只是用户并未要求的重复叙述。任务列表加上子技能自身的输出，就是完整记录。子技能的结果说明属于其输出，而不是交接叙述：在引导和专家流程中，架构师和分析师的“已写入 <path>”收尾信息始终要发送。 **管理员绝不复述子技能的执行过程。**部署、验证和示例数据步骤属于建模器子技能，该子技能以内联方式运行（Step 6.7），并以其自身克制的语气进行说明。遵循建模器的指示时，请遵守建模器的“说明克制”规则，不要再额外添加一层管理员说明：不要说 “匹配步骤已完成”、“应用前正在确认产物”、“现在正在填充示例数据”、“八张表中有七张确认正常……”，也不要说明临时错误及其自行修正的情况（“那个 ERR 只是暂时的小问题”）。这些内容正是建模器“说明克制”部分要求删去的内容；额外输出管理员级别的说明，会重新引入克制规则要消除的噪声。如果你正在说明部署进行到哪一步，超出了建模器自身规则允许的范围，那就是用错误的语气做建模器的工作；请停下来，让子技能用自己的语气说明。

管理员对话中也禁止使用技术 / DBA 术语，标准与建模器的禁用词列表相同。面向用户的文字中不要出现这些内容：FK、orphan(s)、idempotent、non-destructive、NOT-NULL 和约束相关表述、junction、FK-dependency order、spec / blueprint 版本号（v5.2、blueprint v3.0），以及原始 snake_case 标识符。改用“记录之间的链接”“可以安全地重复运行”“关联记录”“你的实时模型”等说法。读者是领域专家（人力资源总监、运营负责人），不是数据建模人员。

每次运行的诊断日志

内部机制只写入每次运行专属的诊断日志，不得写入对话。管理员在 Preflight 开始时仅采样一次运行 ID（RUN_ID="run-$(date -u +%Y%m%d-%H%M%S)"），之后不得再次采样；每个阶段都将 .tmp_admin/<run_id>/diag-<role>.log 写入同一个文件夹（diag-admin.log、diag-architect.log 等）。日志尽力写入（写入失败不得阻断运行），仅用于诊断（不是决策日志——决策记录在 customizations.yaml 和 git 中；快速运行的 auto-picks.md 是每次运行的诊断文件，不是策略记录，参见 references/fast-flow.md），除失败运行时的运行文件夹路径（Step 6.8）外，绝不得在对话中提及日志。完整机制——log_diag 辅助程序、各角色文件命名表和日志规则——见 references/output-discipline.md。

---

任务跟踪（常驻摘要；规则见 references/task-tracking.md）

管理员使用 harness 任务工具（TaskCreate / TaskUpdate / TaskList / TaskGet）处理两件事。完整机制、响应顺序和措辞规则以 references/task-tracking.md 中的规范文本为准；本节仅说明管理员的任务。

流水线任务（计划）。 第 1.1 / 1.3 步完成处理且所有范围标记问题均已回答后，按流水线顺序为计划中的每一行创建一个任务，主题必须与第 6.5 步的行格式表完全一致（其中包含 slug 或显示名称，最终报告据此标识项目）。不要加前缀。然后将它们串联起来：除第一个任务外，每个流水线任务都设置 addBlockedBy: [<前一个流水线任务的 id>]，在各项目之间保持连续，因此顺序体现在列表本身，而非编号中。子技能通过 addBlocks 将各自的阶段任务关联到流水线任务，因此在子技能的阶段完成之前，流水线任务会显示为受阻。仅由管理员执行的操作（第 5 步，包括 Get started）不创建任务。子技能进入时会创建自己的 Design › / Match › / Apply › 阶段任务；管理员绝不创建、编辑或完成这些任务。验证子技能的输出产物后，管理员将其流水线任务设为 completed，并在描述中填写一行摘要；若失败，任务保持 in_progress，并填写原样的错误消息。

台账阶段：范围标记（第 6.4 步）。 推断后仍为 ? 的每个标记问题都变成一个 Q: 任务（主题 = Q: + 完全照抄的第 6.4 步问题措辞；每个标记对应一个问题对象；每次 AskUserQuestion 调用最多四个）。这些 Q: 任务排在流水线任务之前，因此没有阶段任务需要阻塞；门槛由规则本身规定：只有当 TaskList 显示没有待处理或进行中的 Q: 任务时，才可创建流水线任务。独立处理（无台账任务，保持不变）：第 0 步的澄清问题、1.1 碰撞小组件、1.3 匹配小组件及其后续问题、“审计两者，不要名称”。1.1 和 1.3 始终要在范围标记台账启动之前完成处理。

预检（在步骤 0 之前运行，每次调用都运行）

预检不会生成聊天输出（见上文的输出规范）。不要宣布预检；绝不要对用户说出“preflight”或“silent”这两个词。先采样 $RUN_ID 并设置 $DIAG_LOG（diag-admin.log），然后不作任何聊天说明地运行四项共享预检，并将结果写入日志。唯一面向用户的输出是停止消息（必需工具无法安装），或用户必须看到的设置操作（安装必需工具、将 CLI 添加到 PATH、指定主机或打开登录链接）。如果所有检查都通过、所有工具均已安装且 CLI 已通过身份验证，则不要说话，让第一条面向用户的内容成为下载里程碑（仅限 URL 请求）、第一个问题或计划。此处采样的 $RUN_ID 将在步骤 6.2 中重复使用 — 切勿重新采样。

运行共享预检：references/preflight.md。 规范检查均列于此处，这是 admin 和全部三个子技能共用的唯一事实来源：

1. 留在仓库根目录（绝不要使用 cd；CLI 会从当前工作目录读取 .env）。
2. 安装支持工具链（Bun、jq、yq） — 自动安装任何缺失的工具；优先使用包管理器，静态二进制文件作为后备；适用于 Windows、macOS 和 Linux，并包含 mikefarah-yq 的防误用保护。
3. 确保已安装并通过身份验证的 semantius CLI — 通过一次 getCurrentUser 探测，合并安装检查、身份验证检查以及 org / ui_baseurl 读取；如果 CLI 缺失则安装（如果已安装但尚未加入 PATH，则使用完整路径调用）；如果没有主机或登录失败，则在后台使用 semantius use <host> 为用户登录，并转达链接。
4. 计算自定义配置文件路径（CUSTOMIZATIONS_FILE="semantius/${org}/customizations.yaml"）。

admin 会在编排运行中执行全部四项检查；然后通过步骤 7.3 的 Run context: 区块将解析出的 org、ui_baseurl 和 CUSTOMIZATIONS_FILE 传递给每个子技能，因此子技能会跳过检查，而不是重复执行。请阅读参考文件，了解每项检查的完整流程、安装矩阵和退出处理表；不要在此处重复这些细节。

---

步骤 0：识别请求类型

此技能首先要做的是对用户的请求进行分类。后续计划取决于此分类。

共有六种请求类型，按大致优先级排序：

类型	触发短语	流程
开始使用 / 入门	“开始使用”、“我是新手，帮我设置好”、“我可以构建什么？”	仅运行 admin（步骤 5.5）：运行预检（安装检查）→ 通过查询数据库验证连接 → 统计已部署的模块 → 指向蓝图库
端到端构建	“帮我构建一个 CRM 并部署”、“端到端设置一个 ATS”、“我需要在我们的实例中启用帮助台”	architect → analyst → modeler
克隆并部署	“克隆 candidate-crm 蓝图并部署”、“以 ats-candidate-crm 为起点并部署”、“部署 X 蓝图的副本”	architect（Catalog-Clone）→ analyst → modeler。将实时表或实时模块连同其数据复制到另一台主机属于传输，而非克隆并部署：转至 semantius-transfer
部署现有制品	“部署此蓝图”、“部署 https://...md”、“部署我工作区中的文件”	（如果是 URL，则先获取）→ analyst（如果是蓝图）→ modeler
检查 / 审计 / 状态	“部署了什么？”、“semantius 的状态”、“审计此文件”	仅运行 admin（不调用子技能链），或转至相应的审计模式
管理操作	“列出模块”、“检查连接”、“轮换 API 密钥”	仅运行 admin（直接通过 use-semantius 操作）。备份和恢复转至 semantius-transfer

如果请求含糊不清，请通过 AskUserQuestion 提出一个澄清问题。不要猜测。

---

第 1 步：检查工作区

判断条件：请求是否已指明明确且无歧义的来源？ URL 或准确的文件路径都能完整确定来源——无需再查找 工件所在的位置。在这种情况下，不要进行常规工作区盘点。请改为：

1. 根据指定来源推导候选 slug（取 URL/文件自身的文件名：it-ops-starter-semantic-blueprint.md → it-ops-starter；无需使用 related_modules/其他元数据，只需取文件名主体）。
2. 仅针对约定目录运行一次精确文件名存在性检查——test -f semantius/blueprints/<slug>-semantic-blueprint.md / semantius/specs/<slug>-semantic-spec.md。文件名必须完全一致，绝不使用 glob，也不允许子串/前缀/后缀匹配。 文件要么命名为 it-ops-starter-semantic-blueprint.md，就是该工件；要么命名为其他名称（v0-it-ops-starter-semantic-blueprint.md、it-ops-starter-v2-semantic-blueprint.md、my-it-ops-starter-semantic-blueprint.md），就不是匹配项——到此为止，不得读取、打开、使用 cmp 比较或提及这些文件。蓝图的名称就是它的文件名；用 *<slug>* glob 匹配，会把“文件名包含该 slug 子串”误当成“就是该工件”，这恰恰弄反了——它会匹配没人指定的带前缀/后缀变体，并让每个变体都额外消耗一次读取和比较。如果不存在完全匹配的文件，就视为未找到：继续执行第 2 步（获取指定 URL），或从头构建，和工作区为空时一样。不要退而搜索“差不多”的文件。
3. 对于指定来源的请求，不要运行工作区根目录扫描。根目录文件的归属问题只与用户未明确指定的工件有关；对于已经明确指定要获取和部署的请求，这无关紧要。如果用户另外按名称提及根目录中的文件，那也属于指定来源，同样执行第 2 步的精确文件名检查（改为针对根目录）即可——仍然不是扫描，也仍然只允许完全匹配。

仅当请求未指定明确来源时（状态检查、“部署了什么”、工作区中没有其他内容可用于消除歧义时单独提出的“部署这个”、入门配置），常规盘点才有意义，因为确实存在需要查明的内容——含糊的请求可能指的是哪个工件（如果有）：

# Primary location (the convention): semantius/blueprints/ and semantius/specs/
find semantius/blueprints semantius/specs -maxdepth 1 -name '*.md' 2>/dev/null

# Workspace-root locations: blueprints/specs sitting at the workspace root.
# Still scope this to any slug hints the request text does contain (e.g. "the ATS
# blueprint" → scope to *ats*), never a blanket `*-semantic-blueprint.md` glob —
# that pulls every unrelated file at the repo root into consideration for zero
# benefit. Only fall back to the fully unscoped glob when the request truly gives
# no slug hint at all (rare: "what's sitting in my workspace root?").
find . -maxdepth 1 -name '*-semantic-blueprint.md' -o -name '*-semantic-spec.md' 2>/dev/null

1.1 就地查找文件，并将已部署的文件复制（绝不移动）到规范文件夹

复制，绝不移动：此技能会在文件所在位置读取文件，并将已部署的文件复制（绝不移动）到规范文件夹。每次部署的具体做法：

• 先用 cp 复制，再进行任何编辑。 一旦确定本次运行要使用根目录级文件，就立即将其复制到 semantius/blueprints/ 或 semantius/specs/（按需通过 mkdir -p 创建），务必在自定义、扩展、重建操作或分析员运行之前完成。规范文件夹中的副本将成为工作路径：所有编辑都针对该路径，因此它仍与已部署的文件完全一致；根目录中的原文件只读取一次，绝不修改（编辑原文件属于错误操作）。
• 规范文件夹中已有不同的副本： 如果该 slug 的规范文件夹副本已存在，且与根目录中的副本不同，请先通过下方的“slug 同时存在于两处”小部件解决，然后将选定的版本设为工作副本。绝不盲目覆盖。
• 如果确定使用的文件已位于规范文件夹中，则它已经是工作路径；无需复制。

此禁令具体禁止移动和删除此技能未创建的文件（文件名模式不能证明文件归属）。必须且理应对本次运行要部署的单个文件进行非破坏性复制；绝不扫描并移动或删除预先存在的文件。

slug 同时存在于根目录和规范文件夹中。 选择本次请求要读取的副本。绝不因此移动或覆盖任何一个文件。

• 无关文件（与本次请求无关）：保持两个副本不变，将其记录到 $DIAG_LOG，不在聊天中提及。不要选定其中一个，也不要提到它。如果文件无关，就不应出现在聊天中。应避免这种情况：用户要求部署 hiring-starter，却宣布存在 real-estate-agent 冲突，之后又承认“（这与您的请求无关）”。
• 要部署的文件： 两个副本可能不同，读取错误版本会带来实际风险，因此不要默默选定。使用 cmp -s 比较：
  • 字节完全相同： 没有歧义。读取规范文件夹中的副本，记录到 $DIAG_LOG，无需询问即可继续。
  • 存在差异： 触发下方的冲突小部件，让用户选择要读取的副本。蓝图（根目录与 semantius/blueprints/）和规范（根目录与 semantius/specs/）都适用。

冲突小部件（仅在要部署的文件存在两个不同副本时使用）：

• 问题："工作区根目录和规范文件夹中各有一个 <slug> 的不同副本。本次部署应使用哪一个？"
• 标题："Which copy"
• 选项：
  1. "Convention-folder copy (Recommended)" — "使用规范文件夹中的副本（标准位置）。最后修改日期：<date>。"
  2. "Root-folder copy" — "改用根目录级副本。文件仍保留在原位；不会移动或覆盖任何内容。最后修改日期：<date>。"

在选项说明中注明每个副本的最后修改日期，方便用户判断哪个更新。无论用户选择哪个，都读取该副本，并让两个文件都原样留在原位。此次消歧仅适用于本次操作，不是长期政策；不要将其写入 customizations.yaml，以后遇到冲突时仍须再次询问。

完成 1.1 后，蓝图和规范会在其所在位置（规范文件夹或仓库根目录）读取；没有任何文件被移动。步骤 1.2（工作区摘要）会读取两个位置的内容。

1.2 工作区摘要

slug 可能位于约定文件夹、仓库根目录，或两处都有；技能会在文件所在位置读取它，但绝不会移动它（依据 1.1）。如果同一个 slug 同时出现在两个位置，除非用户通过 1.1 中的冲突选择器选了根目录副本，否则摘要应优先使用约定文件夹中的副本，作为防御性回退。

对于每个候选文件，只读取前置元数据（前 30 行就足够）。提取：

• artifact（semantic-blueprint 与 semantic-spec）
• version（蓝图和规格；文件格式版本，"3.x"）
• system_slug
• reconciled_at 和 source_blueprint（仅限规格）

构建工作区摘要：

Workspace artifacts:
  semantius/blueprints/
    - ats-candidate-crm-semantic-blueprint.md  (artifact: semantic-blueprint, version: "3.1", slug: ats-candidate-crm)
  semantius/specs/
    - ats-candidate-crm-semantic-spec.md       (artifact: semantic-spec, version: "3.1", slug: ats-candidate-crm, reconciled 2026-05-25)

如果请求中提到了 URL，请计划先获取该 URL（步骤 2）。

如果请求通过路径或名称提到了特定文件，优先使用该文件，而不是自动发现。如果用户指定的位置与文件实际所在位置不符（例如，用户说“从根文件夹中获取”，但唯一匹配项位于 semantius/blueprints/），只需直接使用明确无误的匹配项。如果确实只有一个匹配项，切勿用一整段话说明位置不符；用户指定的是工件，而不是路径，位置修正只是 $DIAG_LOG 中的事务性记录。只有确实存在两个候选项且必须择一时，才用一行话说明。

工作区摘要本身是内部信息：它会写入 $DIAG_LOG，而不会发到聊天中。用户不需要在计划之前看到前置元数据转储（version、实体数量、“reconciled” 日期）。开场应直接说明计划，而不是先罗列文件。以下 1.3 节所述情况除外。如果现有工作区工件与用户的请求匹配，在制定计划前必须告知用户。禁止展示无关工件的规则不适用于用户刚刚请求的内容与 slug 匹配的工件。

1.3 匹配检查：告知用户可能满足请求的现有工件

在构建任何计划之前，管理员会检查工作区中是否已有可能满足用户请求的蓝图或规格。如果有，管理员必须告知用户，并让用户选择部署现有工件、重新开始或先进行审计。如果已有匹配的蓝图却悄悄新建蓝图，或者用户不知道有现存规格却悄悄通过该规格部署，正是本节要避免的失败情形。

**例外：精确来源豁免——完全跳过选择器。**上述选择器用于解决用户所指工件的歧义。如果同时满足以下两项，就不存在歧义，因此绝不能触发选择器：

1. 请求指定了精确且明确的来源：URL 或精确的文件路径／名称。（根据下文“如何判定匹配”中的测试，基于 slug／关键词相似度推断的匹配不符合条件——这正是选择器要处理的歧义情况。）
2. 工作区中已有该来源对应的蓝图或规格，并且已确认它与指定来源逐字节相同（获取来源——步骤 2——并按照步骤 1.1 的比较方式，使用 cmp -s 与工作区副本进行比较）；或者，如果是规格，其 source_blueprint 与逐字节相同的蓝图一致，且规格的协调时间为该蓝图当前内容的时间或之后。

两项都满足时，无需做选择：工作区工件逐字节就是用户所请求的内容，而且已经完成协调。将匹配结果记录到 $DIAG_LOG，然后直接制定计划（如果现有规格仍是当前版本，则通过建模器部署；否则按蓝图 → 分析器 → 建模器的流程执行）。对于已经确认与用户明确请求完全一致的文件，询问“你想怎么做？”并不是在解决歧义，而是在制造歧义，只会浪费用户的时间。如果获取的来源与工作区副本哪怕只有细微差异，该例外也不适用，应改用常规匹配检查选择器（差异确实造成了歧义：用户是想应用更新，还是想保留现有内容？） 什么情况算匹配。 遍历 Step 1.2 工作区摘要中的每个蓝图和规格说明，并针对用户的请求文本应用以下测试：

1. Slug 匹配。 从用户请求中推导候选 slug（例如，“roadmap planner” → roadmap；“ATS for our recruiting team” → ats、recruiting、ats-candidate-crm）。任何 system_slug 等于某个候选 slug，或是某个候选 slug 的子串或超串的工件，都是匹配候选项。
2. 系统名称匹配。 任何 system_name（不区分大小写，并忽略 “and”、“the”、“for” 等填充词）与用户请求共享两个或更多内容词的工件，都是匹配候选项。示例：请求“product roadmap planner”会匹配 system_name: Product Roadmap，因为两者都包含 product 和 roadmap。
3. 标语／描述匹配。 任何 tagline 与请求共享显著动词短语的工件，都是匹配候选项（请求“collect ideas and defects, prioritize them”与标语“Capture ideas and defects, prioritize them, and build a release plan”匹配）。

一次请求可能产生零个、一个或多个匹配候选项。必须显示所有候选项，不得悄悄选定其中任何一个。

匹配后的操作。 在调用任何子技能之前、构建计划之前，调用 AskUserQuestion。问题格式：

• question："我在你的工作区中找到了看起来已涵盖你请求的 <file>（slug <slug>，<system_name>）。你想怎么做？"
• header："现有工件"
• multiSelect：false
• options（按以下顺序）：
  1. label "部署现有的 <blueprint|spec>（推荐）"，description："直接使用 <file>。跳过新建。流程：<蓝图匹配时 analyst → modeler；规格说明匹配时 modeler>。"
  2. label "先审计／检查现有工件"，description："对 <file> 运行审计，以便你在决定前了解其中内容。不会写入你的语义模型。"
  3. label "重新开始（新建）"，description："忽略 <file>，从头设计一个全新的方案。系统会询问你要将现有文件移到哪里，以免意外重复使用（管理员绝不会删除其未创建的文件）。"
  4. label "取消"，description："停止操作，不做任何事。"

多个匹配候选项。 当工作区中有多个匹配工件时（例如，同一个 slug 同时有蓝图和规格说明，或有两个不同的 slug 都可能是用户所指），在问题正文中列出它们，并让用户选择要处理哪一个（AskUserQuestion，multiSelect: false，每个候选项各一个选项，另加“重新开始”和“取消”）。该工具每个问题接受 2 到 4 个选项，因此最多将 2 个候选项列为选项（选择 slug 或系统名称与请求最匹配的两个）；如果候选项更多，则在问题正文中列出所有候选项，并以 "如果列表中没有你要找的候选项，请输入另一个候选文件的名称。" 结尾（该工具会添加自己的自由文本输入栏；绝不要列出“其他”选项）。用户选定候选项后，再对该文件显示上面所述的单一匹配选项控件（部署／审计／重新开始／取消）。绝不要悄悄挑选“更新的那个”或“匹配度更高的那个”——由用户决定。

选择选项 3（重新开始）时。 后续调用 AskUserQuestion（multiSelect: false，2 个选项），询问要将现有工件移到哪里："移到 semantius/archive/（推荐）" 或 "保留原位；我会为新版本指定不同的 slug"。如果要移到其他文件夹，应在工具的自由文本输入栏中填写，不要将其列为选项。管理员绝不会删除预先存在的文件（依据本 SKILL 底部的规则）；只能移动文件，而且必须得到用户的明确指示。 针对选项 1 / 2。 跳过 Step 0 的分类结果，直接进入相应的流程（选项 1：通过 Step 6 部署；选项 2：架构师审计或分析师审计）。用户在此处的选择优先于 Step 0 对请求的原始分类。

请在检查之后、规划之前运行此检查，绝不能在计划制定完成后运行，这样计划才能基于用户已知情的选择制定。规划之后才触发匹配检查就太晚了：计划中的叙述已经与接下来要做的事情相矛盾。

“不得倾倒清单”的规则仍适用于无关的制品。 工作区中杂乱堆放着以往无关工作的蓝图，不会触发此组件。只有 slug、system_name 或 tagline 与当前请求匹配的制品才会在此处显示。其他所有内容都按 Step 1.2 的规定保留在内部。

---

Step 2：获取远程制品（仅当输入为 URL 时）

当用户提供 http(s):// URL 时，必须先获取该 URL，再执行任何其他步骤，并使用 Step 6.1 中规范的获取、验证和放置流程：使用 curl -s -L 将文件写入 .tmp_admin/<run_id>/incoming/，验证前 30 行能否解析为 front-matter，且其中包含已知的 artifact: 值，然后将文件移至 semantius/blueprints/<system_slug>-semantic-blueprint.md 或 semantius/specs/<system_slug>-semantic-spec.md（按需创建文件夹）。绝不要使用 WebFetch。

若获取失败（curl 退出码非零、文件为空、没有 front-matter 或 artifact: 值未知），请停止并逐字报告失败信息；不要猜测。工作区根目录下的 semantius/ 文件夹是这些制品的正式存放位置（与插件安装位置不同，插件安装在用户的 Claude Code 插件文件夹中，而非其项目仓库中）。

成功后，输出下载里程碑消息（遵守输出规范）：每个 URL 立即输出一行，前提是其 front-matter 已通过验证；行中须说明设计名称（使用其 system_name）和源主机，例如 “已从 semantius.com 下载 Hiring Starter 蓝图。”（若为规格，则为 “已从 semantius.com 下载 Hiring Starter 规格。”）。这一行是此步骤唯一的聊天输出；文件存放位置、暂存文件夹和验证情况都属于 $DIAG_LOG 内容。如果文件已存在且字节完全相同（Step 1.3 绕过），不得预先播报获取操作（“正在获取蓝图……”），也不得额外输出第二行：里程碑消息仍写作“已下载……”，因为文件确实已下载。

---

Step 3：规划流程

根据 Step 0 得出的请求类型以及 Step 1/2 确定的工作区状态，决定要调用哪些子技能，以及调用顺序。

决策表

请求类型	工作区状态	计划
端到端构建	空工作区	architect (Create-Greenfield) → analyst → modeler。不会触发范围标志问题（不会询问 customize、review 或 deploy）：architect 的交互式 Create 流程本身就是设计，而构建请求默认包含 deploy（在专家流程中，只有用户对 architect 收尾时的“现在部署吗？”回答“是”后才会执行；回答“否”则在设计完成后结束运行）。创建的蓝图会成为步骤 6 的项目；modeler 写入前自己的“是/否”确认是唯一关卡（在快速运行中，设计步骤中的同意即为确认）。请参阅下文“全新构建和克隆构建跳过范围标志”以及模式 4。
端到端构建	已有蓝图，无规格说明	**首先运行步骤 1.3 的匹配检查。**如果蓝图与请求匹配，用户在 1.3 的选择将决定运行路径（部署／审计／重新开始）。如果 1.3 未找到匹配项（工作区中的蓝图无关），则仅当用户的请求明确针对该蓝图时，才将工作区蓝图作为唯一项目交给步骤 6；否则按空工作区处理。绝不能在用户未提及工作区蓝图时悄悄使用它。
端到端构建	已有规格说明	**首先运行步骤 1.3 的匹配检查。**如果规格说明与请求匹配，用户在 1.3 的选择将决定运行路径（部署／审计／重新开始）。如果 1.3 未找到匹配项（规格说明无关），则按空工作区处理，并运行全新构建 architect。绝不能在用户未提及工作区规格说明时悄悄使用它。
克隆并部署	空工作区	architect (Create-Catalog-Clone) → analyst → modeler。与全新构建类似，architect 会创建制品，因此不会触发范围标志问题；deploy 默认包含在内。克隆的蓝图会成为步骤 6 的项目。
部署现有项目	任意（1 个或 N 个蓝图／规格说明）	**交给步骤 6。**无论项目数量多少，都统一走此部署路径。范围标志（customize／review，以及 deploy）会按照下文“在展示计划前解析范围标志”优先处理（在 6.4.1 推断；含义不明确时会询问），因此，即使只说“部署这个”，也会先询问是否进行自定义，然后才开始执行。
审计	已指定蓝图	对该蓝图运行 architect (Audit)（不会经过步骤 6）。
审计	已指定规格说明	对该规格说明运行 analyst (Audit)（不会经过步骤 6）。
审计	两者都有，未指定名称	询问要审计哪个（AskUserQuestion，multiSelect: false，3 个选项：蓝图、规格说明、依次审计两者）。
状态	不适用	仅限管理员（步骤 5）。
管理（状态、列表、健康状况）	不适用	仅限管理员（步骤 5）。备份和恢复：semantius-transfer。

为什么所有部署操作都走步骤 6：无论是一个项目还是多个项目，管道都相同。步骤 6 包含自定义／部署标志处理、自定义文件交接以及统一报告。全新构建和目录克隆也会通过步骤 6 执行 analyst → modeler 阶段并生成统一报告，但它们不会触发 customize／review／deploy 问题：architect 的 Create 流程已经涵盖设计，且 deploy 默认包含在内（请参阅“全新构建和克隆构建跳过范围标志”）。只有纯 architect 操作（审计蓝图）、纯 analyst 操作（审计规格说明）和仅限管理员的操作（状态、备份、健康状况）会绕过步骤 6。任何最终会写入实时语义模型的操作都要经过步骤 6。

在呈现计划前解析范围标志

在创建流水线任务前，先解析范围标志（范围标志先于计划）。这些是路由决策，而非确认：customize=yes 会生成 architect → analyst → modeler 的蓝图流程，customize=no 会生成 analyst → modeler 的蓝图流程，因此在解析这些标志前，计划不可能正确。全新构建和目录克隆会直接跳过（不会触发范围问题；防止错误的规则：“create a task list”绝不能导致出现 “Deploy the task-list design as designed, or edit it first?”）。对于现有制品（工作区文件、Step 1.3 匹配项或 Step 2 中获取的 URL）：

• 单个已识别制品（一个命名文件、一个获取的 URL、一个 Step 1.3 匹配项）：在此处解析其标志，早于创建流水线任务。已有 front-matter（system_name），因此问题措辞已经完整。
• 多来源 / glob（仅在 Step 6.1 中枚举的项目）：在 Step 6.4 中解析每个项目的标志，仍须早于在 Step 6.6 中为该项目创建流水线任务。

使用 Step 6.4 中的先推断后提问流程（意图表 6.4.1、Step 6.4 中的准确措辞、流程 6.4.2）；不要在此重新推导。这些是范围问题，不是部署确认，因此单次写入门控规则绝不会抑制它们：单说“deploy this”会让 customize 保持为 ?，必须触发 customize 问题。标志问题通过问题台账运行（见上文的任务跟踪）：创建任何流水线任务前，TaskList 必须显示没有未完成的 Q: 任务。

交互流程开关（无问题）

交互流程是保存在 $CUSTOMIZATIONS_FILE 中的 .interaction_flow 开关：guided、expert 或 fast（未保存任何值时的默认值；规则见：references/interaction-flow.md）。在任何子技能启动前于此处处理：

1. 如果请求中提到“expert flow”、“guided flow”或“fast flow”，则写入 .interaction_flow（expert / guided / fast），并添加常规来源注释（references/customizations-protocol.md 7.5，第 4a 步），然后按 interaction-flow.md 第 2 节的内容播报一行文字。
2. 否则，如果 .interaction_flow 为 expert，则播报一次：“正在使用 expert flow。”
3. 确定本次运行的流程，并通过 Interaction flow: 传递给每个子技能（Step 7.3）：
   • 重建：始终使用 expert，无论开关为何；不播报任何内容。
   • 开关为 expert 或 guided：使用开关值。
   • 开关为 fast 或未设置，且为新构建（Architect mode: create）：使用 fast；但只有当请求要求对本次构建进行引导时才使用 guided（references/interaction-flow.md，第 2 节），并播报一次 “本次将使用 guided flow。”，不写入任何内容。
   • 开关为 fast 或未设置，且为其他任何运行（从现有设计开始）：使用 guided；只有当开关已保存为 fast 时，才播报一次 “Fast flow 仅适用于新构建；本次运行将使用 guided flow。”

这不是范围标志：无需创建 Q: 任务，也不显示小组件。

快速流程

快速运行时，现在以及上下文重置后，都要阅读 references/fast-flow.md。设计步骤以一个是否继续的问题结束；用户回答“是”后，在建模器提出最后的样例数据问题之前，任何子技能都不得再提问，因为用户一次性批准了整个构建，之后每次停下来都会违背这一承诺，而结束摘要就是供用户审核的内容。用户回答是否继续的问题后，将标记写入流水线任务的描述中（fast: go-ahead given / fast: guided flow for this build；references/fast-flow.md，第 3 节）。进入分析师之前，以及进入建模器之前，都要读取流水线任务描述中的标记（TaskGet）：fast: go-ahead given 表示传入 Interaction flow: fast；fast: guided flow for this build（用户选择了“沿途问我”）表示传入 guided。

退出检查（快速流程）。 在建模器发送结束消息前，检查其草稿是否包含：(a) [在 Semantius 中打开 <System Name> →](<ui_baseurl>/<module_slug>)，(b) 已部署规范的下载链接，以及 (c) 样例数据问题，除非用户已经回答。根据建模器的 Closing Contract，补上缺少的内容。在结束消息发出前（即完成 Verify 任务的那条回复中）写入 log_diag "fast: close-out verified"，因为结束消息的文本之后不会再调用工具。

呈现计划

到这一步，范围标记已解决，因此计划会反映这些标记并显示正确的步骤数。流水线流程（构建、克隆、部署）不会在此处构建并运行计划——它们会转交给第 6 步，该步骤会在第 6.4 步解决每项的标记后，于第 6.6 步创建流水线任务。只有绕过第 6 步的流程（审计、管理）才会在第 3 步构建可运行的计划。切勿在第 3 步构建部署计划后直接进入子技能：这样会跳过第 6.4 步。

计划就是任务列表：每行计划创建一个任务，然后在聊天中发出一句引导语（单一写入关卡：不预先显示“是否继续？”小组件；建模器会自行询问是或否）。计划行编写规则、四种计划模式（只读／限定写入／网络获取／从头构建），以及多个项目的完整示例，见 references/plan-shapes.md。规范的限定写入模式由两个任务和一句话组成：

• 任务：Match ats-candidate-crm against your live semantic model and write the spec.
• 任务：Apply ats-candidate-crm to your live semantic model.
• 聊天："这是计划。匹配步骤会问你几个合并／复用问题，且不会写入任何内容；应用步骤会先向你展示变更内容，在你确认后再更新实时模型。"

然后运行流水线；建模器是唯一的写入关卡。如果用户看过计划后想要更改范围或停止，可以在聊天中说明；重新解决标记（第 6.4 步），将过时的流水线任务设为 deleted 并创建新任务，或者妥善停止（“已取消。未做任何更改。”）。此时尚未运行任何操作，而且建模器仍会把关每一项写入，因此不会发生任何意外写入。

---

第 4 步：执行流水线

对于计划中的每个步骤，都要在主线程中内联运行相应的子技能（在同一对话上下文中加载并遵循其 SKILL.md），以便其 AskUserQuestion 提示直接发送给用户。

三个流水线子技能都是交互式的，因此都必须内联运行。 架构师的自定义流程是只有用户才能结束的交互式编辑循环；分析师会在协调过程中提出合并／复用／晋升／冲突问题；建模师在每次写入前都会询问是否执行。**切勿将交互式子技能作为 Agent 工具子代理启动：**子代理在隔离上下文中运行，无法进行这些对话，因此它的问题无法传达给用户，流水线也会因此停滞或只能猜测。Agent 工具仅用于真正非交互式的辅助工作——架构师／分析师／建模师流水线步骤都不符合这一条件。

子技能调用模式

对于每个步骤：

1. 执行前检查：确认输入产物存在于预期路径。运行 TaskList，然后将该步骤的流水线任务设为 in_progress。
2. 内联调用：在对话中建立运行上下文（第 7.3 步），然后在同一上下文中进入子技能并遵循其 SKILL.md。让其 AskUserQuestion 提示直接显示给用户；不要代替用户作答（在用户同意后的快速运行中，子技能会按自己的规则选择各项答案并记录；管理员仍不作任何决定）。子技能会创建并推进自己的阶段任务；管理员不得操作这些任务。子技能会生成自己的输出产物。
3. 验证：确认预期的输出产物已在工作区的预期路径中生成。
4. 记录：运行 TaskList，然后将流水线任务设为 completed，并在其描述中用一行总结（输出路径、关键指标）。不要在聊天中汇报；应在最终报告（第 6.8 步）或收尾说明（对于跳过第 6 步的审计运行，见第 8 步）中向用户传达总结。

如果任何子技能停止运行、报告错误，或提出管理员无法代替用户回答的问题，立即在该处停止流水线，并逐字转述子技能的最后一条消息。管理员不得尝试恢复或猜测。（在用户同意后的快速运行中，子技能不会提问，因此只有停止运行或报错才会中断流水线。）

常见子技能触发条件（确保管理员正确调用）

子技能	调用时机	输入产物	输出产物
semantius-architect	构建新蓝图、克隆目录中的蓝图，或审计／扩展／重建现有蓝图	（无，或 Audit／Extend／Rebuild／Customize 模式所需的 <slug>-semantic-blueprint.md）	<slug>-semantic-blueprint.md
semantius-analyst	将蓝图与实时目录协调，生成可部署规范	<slug>-semantic-blueprint.md	<slug>-semantic-spec.md
semantius-modeler	部署已协调的规范	<slug>-semantic-spec.md	（实时目录变更）

版本化输入门槛

每个子技能都会对输入执行自己的版本契约检查。管理员信任这些门槛，不预先检查版本。如果子技能因版本不匹配而拒绝输入，请逐字转述拒绝消息。

---

第 5 步：仅限管理员的操作

不涉及架构师 / 分析师 / 建模师链路的操作。管理员直接通过 use-semantius（CLI 模式）执行这些操作，无需启动子技能 Agent。完整流程（确切的 Status 输出模板、列表包装器和健康探测）位于 references/admin-operations.md；执行这些操作时请加载该文件。

操作	触发方式	功能
Status（5.1）	“部署了什么？”，“semantius 的状态”	显示工作区工件和实时模块（实体 / 权限数量、上次部署时间）。只读。
Backup（5.2）	“备份目录”，“快照模块 X”，“恢复此备份”	此处不执行：转至 semantius-transfer，它会通过 CLI 的 export_module 导出为可恢复文件，并通过 import_module 恢复。
Listing（5.3）	“列出模块 / 实体 / 权限 / 用户 / 角色”	便捷的只读包装器，生成易读的表格。
Health（5.4）	“检查连接”	运行 semantius whoami 和 semantius ping，读取一个已知内置项，并报告 OK / FAIL。

开始使用（5.5）仍保留在下方：它是一种顶层请求类型（第 0 步），有自己的引导流程。

5.5 开始使用（入门）

开始使用 — 新用户进入平台的入口。它会确保所需工具已就绪，通过查询实时数据库验证连接，报告当前已部署的内容，并引导用户前往 https://app.semantius.com（注册或访问控制面板）以及蓝图目录，以便用户搭建适合自己的数据平台。可随时安全运行；可通过“开始使用”“我是新用户，帮我设置好”等类似请求触发（无需外部命令）。

流程：

1. 运行共享预检（references/preflight.md）。这是安装检查：如果缺少 semantius CLI、Bun、jq 或 yq，就会安装它们（适用于 Windows / macOS / Linux），并完成连接设置（未配置主机时询问要连接哪台主机，然后启动登录流程并提供用户可打开的链接）。成功后即可获取当前的 org 和 ui_baseurl。如果某项检查中止了流程（例如无法安装某个工具，或用户尚未登录），请说明情况并停止；尚无实例的用户应前往 https://app.semantius.com 注册，获取其实例地址——只有平台可访问后才能开始使用。

2. 通过查询数据库验证连接。 确认目录确实能读取数据，而不只是 CLI 已通过身份验证：

   semantius call crud read_entity --single '{"filters": "table_name=eq.users"}'   # a known built-in must read back
   semantius call crud read_module '{}'                                            # the deployed modules
   

   如果出现任何错误，请原样说明错误并停止：平台可访问，但目录无法查询，用户必须先解决此问题。

3. 统计已部署的模块。 根据 read_module 的结果，统计自定义数据模块：这类模块的 domain_code 列非空（这是部署流水线的标记），区别于平台内置模块。此数量就是“目前的数据平台”模块数。

4. 报告结果，并引导用户查看目录。 使用通俗表达，不要直接显示 slug：

   • 尚未部署任何内容（没有自定义模块）： “已连接到 <org>，但目前还没有上线的自定义数据模块。Semantius 围绕可定制蓝图构建——这些预先设计的数据模型可供你调整，打造高度定制化的数据平台——我可以为你部署一个。你的控制面板位于 https://app.semantius.com。”
   • 已部署部分模块： “已连接到 <org>，目前有 N 个数据模块上线：<通俗易懂的名称>。目录中的每个系统都是可定制的蓝图，你可以调整它们，打造高度定制化的数据平台。你的控制面板位于 https://app.semantius.com，随时告诉我即可查看完整状态。”

5. 提供下一步选项，不要强迫用户操作。 用一句简短的话询问用户是想让我部署目录中的蓝图、根据一个想法构建新系统，还是查看完整状态。然后等待。

对目录的操作仅限只读。唯一的写入操作是安装工具，以及使用固定主机的登录（用户指定主机后执行 semantius use）；用户请求开始使用即表示已授权这些操作。

---

第 6 步：流水线执行

部署请求可以包含一个或多个来源：两个 URL、三个本地路径、像 ./blueprints/*.md 这样的 glob，或任意混合形式。无论收到多少项，管理员都会按同一份清单逐项处理。

用户在单项处理中作出的决定（跨模块冲突、主机主数据选择、缺少所有者时的处理方式）会作为长期策略记录在 semantius/<org>/customizations.yaml 中，因此本次运行中的后续项目以及今后的每次运行都会自动解决这些情况，无需再次询问。避免重复提示正是这样做的目的。

6.1 解析来源

从左到右遍历请求中列出的部署来源（作为插件命令调用时，它们会作为命令参数传入；单独运行时，从用户消息中读取）。每个来源属于以下类型之一：

• http(s)://... URL：通过 curl -s -L 下载（绝不使用 WebFetch）。先保存到 .tmp_admin/run-<id>/incoming/<derived-filename>.md 以供验证；成功后，移至工作区制品文件夹（semantius/blueprints/<system_slug>-semantic-blueprint.md 或 semantius/specs/<system_slug>-semantic-spec.md），并按步骤 2 输出一行下载里程碑消息（“已从 semantius.com 下载 Hiring Starter 蓝图。”）；这是获取来源时唯一的聊天输出。
• 本地文件路径：接受约定文件夹（semantius/blueprints/<file>、semantius/specs/<file>）和工作区根目录下的路径。仅位于根目录的制品必须按照步骤 1.1 的复制规则，在任何子技能运行前复制到约定文件夹；之后的运行中，约定文件夹中的副本将作为解析后的工作路径。根目录中的原文件只读取一次，之后绝不编辑。（复制，绝不移动；绝不编辑根目录中的文件。）
• Glob 模式：在工作区中展开。合适的 Glob 模式包括 semantius/blueprints/*.md、semantius/specs/*.md 或针对工作区根目录的 ./*.md。顺序按 shell 返回的顺序；用户也可以通过显式列出来源来重新排序。

构建一个包含已解析文件路径（已验证的最终位置）的扁平列表。验证每个文件：

• 文件存在且可读。
• 前 30 行可解析为 YAML front matter。
• 存在 artifact: 键，且其值是管理员已知的类型（semantic-blueprint 或 semantic-spec）。

任何一项失败（curl 返回非零状态、文件缺失、front matter 格式错误、artifact: 值未知），都应停止，并以通俗易懂的语言指出失败的来源。不要回退，也不要悄悄跳过问题来源。

如果制品文件夹尚不存在，则创建它们：mkdir -p semantius/blueprints semantius/specs。

6.2 复用运行 ID

$RUN_ID 已在预检阶段采样一次（它是整个调用唯一的时间戳）。在此处复用；不要再次调用 date——第二次采样会导致下载和诊断日志被分到两个名称不同的文件夹中。

# RUN_ID comes from Preflight. Same folder already holds diag-admin.log.
RUN_DIR=".tmp_admin/$RUN_ID"
mkdir -p "$RUN_DIR/incoming"

.tmp_admin/ 已列入 .gitignore。运行完成后，文件夹仍会保留在磁盘上；下一次运行会使用自己的文件夹。由用户负责清理。运行文件夹包含待处理下载（incoming/）和各 Agent 的诊断日志（diag-<agent>.log，参见“输出规范”部分）；快速运行时还会包含 auto-picks.md（本次运行中为用户挑选的内容列表；references/fast-flow.md，第 5 节）。不生成决策日志：持久化决策保存在 $CUSTOMIZATIONS_FILE 中（按组织维护并提交），参见步骤 7。

6.3 检查每个制品

对每个已解析路径，仅读取前 30 行并提取：

• artifact（semantic-blueprint 或 semantic-spec）
• system_slug
• system_name（面向用户的显示名称；取自 front matter 或顶层 # <name> 标题）。关闭流程中的通俗链接文本（步骤 6.8 / 步骤 8）需要此名称；面向用户的文案中应优先使用此名称，绝不使用原始 slug。
• naming_mode（存在 → greenfield 蓝图；不存在 → catalog-clone 蓝图；对规格不适用）

完整文件通过路径引用交给子技能。不要将正文读入管理员上下文。

6.4 解析范围标记（先根据意图推断，再询问剩余项）

新建和克隆的项目会完全跳过 6.4。 如果该项目是本次运行中架构师刚创建的蓝图（新建构建或目录克隆），则不适用范围标志：Create 阶段就是交互式设计，默认会执行 deploy，而 customize / review 不适用。无需提问，直接将这类项目交给 analyst → modeler（Step 6.5）。在专家流程中，架构师会在结束时询问“现在部署吗？”；如果回答否，本次运行会在设计完成后结束，analyst 和 modeler 任务保持 pending，并由 Step 8 收尾。仅对本次运行开始前已存在的工件（工作区文件或在 Step 2 中获取的 URL）解析范围标志。

顺序（硬性规则）：对于预先存在的工件，必须在 6.6 创建流水线任务之前解析范围标志。 对于单个已识别的预先存在工件，这已在 Step 3 中完成（“在展示计划前解析范围标志”）；在此处重新读取已解析的值，并验证其符合项目的工件类型（蓝图使用 customize + deploy；规范使用 review + deploy）。对于在 Step 6.1 中首次枚举的项目（多源 / glob），在此处解析这些标志。这些是路由 / 范围问题，不是部署确认，因此“无需预先设关卡”规则不会抑制它们：仅说“部署这个”会让 customize 保持 ?，必须在计划之前、进入任何子技能之前触发 customize 的 AskUserQuestion。这条规则的具体执行方式是：标志问题属于 Q: 账本任务；只要 TaskList 显示有 Q: 任务处于待处理或进行中，6.6 就不得创建流水线任务。

每个项目最多适用三个标志。实际适用的两个标志取决于工件类型：

标志	适用于	默认值	决定事项
customize	蓝图输入	no	决定是在构建并应用之前编辑设计（实体、关系），还是按设计部署。
review	规范输入	no	决定是在应用之前将规范与实时模型对照检查差异，还是直接应用。
deploy	两者	yes	决定是否将结果应用到实时模型，还是仅进行试运行（仅构建）。

必须询问标志时的确切措辞。 当推断（6.4.1）无法明确判断某个标志，且流程（6.4.2）触发 AskUserQuestion 时，请逐字使用以下措辞；将设计的显示名称（其 system_name，例如 “Hiring Starter”）填入所有 <system_name> 的位置。为确保提示清晰，需遵守以下两条规则，因为只有“按原样部署”这个选项标签、却没有影响说明，正是本段规则要避免的含糊提示：

1. 每个选项的说明都要写明具体的后续影响：接下来会运行什么，以及会或不会向实时模型写入什么。 标签写出选择，说明写明后果。
2. “按设计”和“直接”指工件的内容，绝不指文件处理。 将源工件复制到 semantius/blueprints/ 是自动操作，绝不是用户的选择（Step 1.1）。选项措辞绝不能让人理解为“使用我找到的文件”或“要不要复制它”；这会将设计决策与复制规则混为一谈，正是需要消除的歧义。

customize（蓝图输入），标题 Edit design?：

• 问题：“按设计部署 <system_name> 设计，还是先编辑设计？编辑会启动交互式流程，以便在构建任何内容之前添加或移除实体并调整关系。按设计部署会使实体列表和关系保持原样。”
• 选项 1（默认）：标签 Deploy as designed (Recommended)，说明 “使用未经修改的设计并部署。不会编辑任何实体或关系。”
• 选项 2：标签 Edit the design first，说明 “先进入交互式编辑流程（添加或移除实体、修改关系）。你表示完成后，我会将编辑后的设计与实时模型对照匹配并应用。” review（规格输入），标题为 Review spec?：
• 问题："直接应用 <system_name> 规格，还是先对照你的实时模型进行审查？审查会显示将发生哪些变化（偏差），然后才会写入任何内容；不会修改你的模型。"
• 选项 1（默认）：标签 Apply directly (Recommended)，描述 "跳过审查，将规格交给应用步骤。应用步骤仍会显示自己的摘要，并在写入任何内容前征求确认。"
• 选项 2：标签 Review against the live model first，描述 "将规格与实时模型的当前状态进行比较，并指出任何偏差。此操作为只读；在你选择继续之前，不会写入任何内容。"

deploy（两者都适用），标题为 Apply?：

• 问题："最后将结果应用到你的实时模型，还是到干运行就停止？"
• 选项 1（默认）：标签 Apply to your live model (Recommended)，描述 "运行完整工作流，并将结果写入你的实时模型。应用步骤会显示摘要，并在写入前征求确认。"
• 选项 2：标签 Dry run (build only)，描述 "构建规格，但不触碰你的实时模型。你会得到规格文件以供检查；不会写入任何内容。"

蓝图输入解析 customize + deploy；规格输入解析 review + deploy。同一项绝不能同时使用 customize 和 review。（访问级别（access_scope）不是管理员范围标志：架构师会在权限步骤中决定访问级别。管理员既不会检测该级别，也不会询问。）

没有访问级别的蓝图始终会进入 Customize。 为蓝图项解析 customize 前，读取工作副本的 frontmatter：yq --front-matter=extract '.access_scope' <working copy>。如果为空（null），则无需询问，直接设置 customize = yes（该项会跳过上述 customize 问题，包括在选择“原样部署”或“只部署”后）：架构师的 Customize 第一步会决定访问级别并在分析员运行前写入该级别。照常解析 deploy。

先进行推断，再提问。 扫描用户请求中的意图动词，并预先填入标志。仅当标志仍存在真正的歧义时，才调用 AskUserQuestion。经验法则：只有明确表示退出的措辞（“原样部署”“只部署”“不做更改直接部署”）才允许跳过先编辑再部署的问题；仅提到部署的动词始终要询问。

6.4.1 意图 → 标志推断表

该表分为两部分，每种工件类型各一部分。选择与当前项目的 artifact: 值匹配的部分，并从上到下逐行查看；第一个匹配项优先。

蓝图输入（artifact 为 semantic-blueprint）：

用户请求中的短语模式	customize	deploy	备注
“为我构建一个 X”、“创建一个 X”、“我需要一个 X”、“端到端设置一个 X”（全新构建：没有预先存在的工件；架构师在本轮创建它）	N/A	yes	全新构建。架构师的交互式 Create 流程本身就是设计，因此没有 customize 问题。默认推断 deploy；modeler 是写入关卡。对此项目跳过 6.4（见上文的全新构建快速处理）。
“按原样部署”、“直接部署”、“不做修改地部署”、“原封不动地部署”、“直接推送部署”、“不做更改地部署”	no	yes	明确选择不进行自定义。跳过两个提问。
“部署这个”、“部署那个”、“部署这些”、“部署所有这些”、“推送这个”、“应用这个”、“让它成为现实”、“实现这个”、“在 semantius 中设置”	?（询问，默认 no）	yes	有部署动词，但没有按原样部署的限定语。跳过部署提问；询问自定义问题。
“为……创建规格”、“协调这个”、“将这个与实时模型匹配”、“如果……会发生什么变化”、“分析这个蓝图”、“试运行”、“仅制定计划”、“只生成规格”、“对照 semantius 检查”	no	no	仅分析意图。推断两个标志；跳过两个提问。
“先自定义这个”、“让我编辑实体”、“部署前调整”、“审查并调整”、“审计并更新”（针对蓝图）	yes	（仍需询问）	明确要求自定义；用户可能只想自定义后就停止，也可能想自定义后再部署。询问是否部署。
“自定义并部署”、“编辑后推送”、“调整并应用”、“审查并部署这个”	yes	yes	两项都已明确。无需提问。
“自定义这个”（没有任何部署动词）	yes	no（推荐）	倾向于选择 no，但需确认一次。
含糊不清：只有 URL，没有动词；“设置这个”；“使用这个蓝图”	?（询问）	?（询问）	通过 AskUserQuestion 回退到默认值。

规格输入（artifact 为 semantic-spec）：

用户请求中的短语模式	review	deploy	备注
“按原样部署规格”、“直接部署规格”、“不做修改地部署规格”、“直接部署”、“不经审查就部署”	no	yes	明确选择不进行审查。跳过两个提问。
“部署规格”、“部署这个”、“推送规格”、“应用这个”、“让它成为现实”、“实现这个”	?（询问，默认 no）	yes	有部署动词，但没有按原样部署的限定语。跳过部署提问；询问审查问题。
“审查规格并部署”、“审计后部署”、“检查规格后再推送”	yes	yes	两项都已明确。无需提问。
“审查规格”、“审计规格”、“检查规格”、“先看看规格”（没有部署动词）	yes	no	仅审查意图。推断两个标志；跳过两个提问。
含糊不清：只有 URL，没有动词；“设置这个”；“使用这个规格”	?（询问）	?（询问）	通过 AskUserQuestion 回退到默认值。

对于 deploy，分类较宽松（倾向于推断）；对于 customize / review，分类较严格（除非提示明确选择不执行，否则倾向于询问）。编辑优先标志一旦出现一次误判，就会悄无声息地跳过用户想要的步骤；相比之下，多问一次的代价很低。

6.4.2 流程

0. 绿地构建／克隆快速分流。 如果该条目是本次运行中架构师创建的蓝图（绿地构建或目录克隆），则停止：范围标志不适用，deploy 默认为是（在专家流程中，由对架构师的“立即部署？”回答“是”来决定），直接将其交给 analyst → modeler。不要为此运行以下步骤。 0a. 没有访问级别的蓝图。 对于蓝图条目，运行 yq --front-matter=extract '.access_scope' <working copy>；若结果为 null → customize = yes（强制：不创建 Q: 任务，也不提问，即使用户表示“按原样部署”或“只部署”也如此），然后仅解析下方的 deploy。
1. 阅读用户的完整请求文本（触发本次运行的消息）。
2. 对每个条目，根据产物选择表格中对应的部分（蓝图或规范），然后从上到下逐项匹配；以第一个匹配项为准。
3. 对于推断后仍为 ? 的每个标志，都通过问题台账提问（references/task-tracking.md，模式 B）：每个标志创建一个 Q: 任务，其主题为 Q: + 该标志在 6.4 中的确切问题措辞，然后每次 AskUserQuestion 调用最多发送四个问题对象；每个问题都要包含其 6.4 标题、两个选项及明确说明影响的描述，并将默认选项标记为 Recommended。每个标志对应一个问题对象，绝不将两个标志合并到同一个问题中。答案记录在该条目上（管道任务创建后，记录在其描述中），并将 Q: 任务设为 completed。TaskList 中没有 Q: 任务是进入 6.6 的前提。
4. 不要叙述推断出的标志（不说 “推断结果：customize=no、deploy=yes。”）：原始标志值属于内部用语。计划引导语会说明最终范围，其中会列出步骤，并指出哪一步会写入实时模型；6.4.3 说明如何更正。标志值应写入管道任务的描述和 $DIAG_LOG。

6.4.3 运行前更改范围

没有预先确认环节让用户选择“更改”。如果用户在看到计划后（在聊天中）要求更改范围，则重新解析本次运行中相关的标志，将已过时的管道任务设为 deleted，并创建新任务。收到明确更正后，不再运行意图推断（用户正在覆盖原有推断）。

6.5 构建清单

对每个条目，根据产物类型和已解析的标志推导其管道（步骤 3 / 6.4 已在此之前解析这些标志；6.5 只读取标志，绝不提问或重新解析）。条目管道中的每个子技能都必须作为独立任务；不要将多个子技能合并为一个任务。 customize=yes 且 deploy=yes 的蓝图应创建三个任务，而不是一个。

每个条目的管道：

输入产物	编辑优先标志	deploy	管道（每个步骤 = 一个任务）
semantic-blueprint	customize=no	yes	analyst Reconcile → modeler
semantic-blueprint	customize=no	no	analyst Reconcile
semantic-blueprint	customize=yes	yes	architect Customize → analyst Reconcile → modeler
semantic-blueprint	customize=yes	no	architect Customize → analyst Reconcile
缺少 access_scope 的 semantic-blueprint	customize=yes（强制，绝不提问；6.4）	yes / no	按上方两个 customize=yes 行处理
semantic-spec	review=no	yes	modeler
semantic-spec	review=no	no	拒绝此条目（无事可做——用一句话说明并跳过）
semantic-spec	review=yes	yes	analyst Review → modeler
semantic-spec	review=yes	no	analyst Review
计划即任务列表：每个流水线步骤创建一个 TaskCreate，按条目顺序排列；任务主题根据下表，使用每个文件的 system_slug（若 slug 缺失，则使用文件名），并遵循 references/plan-shapes.md 中的计划行编写规则（以动作开头，使用“你的语义模型”，文件名放在收尾说明中，而非主题里）。计划仅供参考（唯一的写入关卡：末尾没有确认控件；创建任务不代表暂停）。

各子技能的任务主题：

子技能	任务主题
architect Create（从零开始）	"为你的 <system> 设计数据模型，梳理其实体及彼此之间的关系（交互式）。"
architect Catalog-Clone	"克隆 \` 设计并以此为起点（交互式）。"`
architect Customize	"审阅并编辑 \`。"`
analyst Reconcile（基于蓝图）	"将 \` 与你的实时语义模型进行匹配，并编写规范。"`
analyst Review（基于规范）	"根据你的实时语义模型审阅 \`。"`
modeler	"将 \` 应用到你的实时语义模型。"`

对于包含多个条目的运行，先创建条目 1 的任务，再创建条目 2 的任务，以此类推；从第二个任务开始，每个任务都使用 addBlockedBy: [<previous pipeline task id>]，将所有条目串成一条链（这就是顺序；因此绝不使用编号：ID 会与子技能自身的阶段任务及 Q: 任务交错）。每个主题都应独立完整；不要压缩重复短语。

references/plan-shapes.md 中提供了涵盖所有标志组合的示例（多条目 analyst → modeler、试运行、自定义、直接部署规范、先审阅再部署）。modeler 会显示自己的摘要，并在写入每个条目前询问最终的“是/否”。

引导句规则： 随任务附上的那一句对话要告诉用户哪个步骤会提问，以及会写入什么；步骤应按其作用命名（绝不使用数字）。如果存在 modeler apply 任务：“这是计划。匹配步骤会向你询问几个合并／复用问题，且不会写入任何内容；应用步骤会先展示变更内容，在你确认后更新实时模型。” 如果不存在 apply 任务：“这是计划。匹配步骤会向你询问几个合并／复用问题；不会对语义模型进行任何应用，规范将写入 semantius/specs/。” 如果没有 analyst 步骤，则删去关于匹配步骤的部分；如果存在 architect 步骤，则添加 “编辑步骤为交互式，直到你表示已完成时结束。” 全新构建的快速流程使用快速流程引导句（见 references/plan-shapes.md 中的 Pattern 4，快速流程变体）。

拒绝 deploy=no 且 review=no 的规范。 如果某个条目解析为这种组合，用一行说明——“`` 是一个设置了 deploy=no 和 review=no 的规范；不会执行任何操作。跳过。”——并在创建任何任务之前将该条目从本次运行中移除。

6.6 展示计划并运行

前置条件：TaskList 中没有待处理或进行中的 Q: 任务（所有范围标志均已回答）。然后按照 6.5 创建流水线任务并将它们串联起来（先全部执行 TaskCreate，然后在同一条回复中对除第一个任务以外的每个任务执行 TaskUpdate ... addBlockedBy），输出引导语句，然后运行（单一写入门控：不预先显示确认控件，无论一个条目还是多个条目）。在快速运行中，每个流水线任务的描述都以标记 fast: awaiting go-ahead 开头（references/fast-flow.md，第 2 节）。

• 运行包含写入操作（任一条目的 deploy=yes）：每个条目的建模步骤都会展示各自的计划摘要，并在写入前询问最终的“是/否”确认——每个需要部署的条目确认一次，在该条目的规格就绪时触发。在快速运行中，设计步骤中的同意即为该确认，建模器不会再次询问。
• 只读运行（deploy=no）：创建任务，输出引导语句，然后运行。
• **更改范围或取消：**如果用户在查看计划后要求更改范围或停止，则重新解析标志（6.4），将过时任务设为 deleted 并创建新任务，或干净地停止。无需控件；尚未运行任何操作，建模器仍会对每次写入进行门控。

如果在 6.1 中执行了 URL 抓取，请先打印 URL 并执行抓取（不会写入实时模型，也不会创建任务），然后继续。

6.7 逐项执行

按用户给定的顺序遍历已解析的列表。遵循该顺序；不要进行拓扑排序。循环依赖是用户错误。

对于每个条目：

**前置条件（硬性门控）：**此条目的范围标志已解析（步骤 3 / 第 6.4 节），其流水线任务也已创建（第 6.6 节）。如果 customize（蓝图）或 review（规格）仍未解析，则停止并先行解析；绝不能在范围标志未解析时进入该条目的第一个子技能。绝不能跳过 customize 问题，直接从步骤 3 的计划进入分析师。

1. TaskList，然后将该项的第一个流水线任务设为 in_progress。不要发送聊天消息：任务状态就是进度记录。不要重复叙述子技能本身会叙述的内容，也不要在子技能之间添加过渡句（不要说 “现在将其应用到你的实时模型……”，也不要预先解释部署步骤），参见 Output discipline 中的“流水线交接不作叙述”。
2. 按照 Step 7.3 的架构说明运行上下文（在对话中说明，不要前置到 Agent 工具调用中）：
   • 始终包含：Run context:、Customizations file:、Interaction flow:（本次运行的流程；快速运行中，在 analyst 和 modeler 执行前，先重新读取流水线任务标记）。
   • Architect 调用：添加 Architect mode:（取值之一：create | catalog-clone | audit | extend | customize | rebuild）和 Input artifact:——这必须是 Step 6.1 中解析出的约定文件夹工作副本（semantius/blueprints/<file>），绝不能是仓库根目录路径。architect 会就地编辑交给它的制品，因此交给它根目录路径会导致根目录文件被修改；请交给它副本。根据已解析的标志确定模式（见 Step 7.3 中的表格）。
   • Analyst 调用：添加 Analyst mode:（普通部署使用 reconcile；其他路径使用 audit / extend / rebuild）和 Input artifact:（约定文件夹工作副本，绝不能是根目录）。
   • Modeler 调用：添加 Input artifact:（规范路径）和 Deploy flag:（根据已解析的部署选择填写 yes / no）。
3. 按 Step 4 的调用模式，在主线程内联执行流水线中的第一个子技能：先说明第 2 步中的运行上下文，然后在同一上下文中遵循子技能的 SKILL.md，使其 AskUserQuestion 提示能触达用户。不要将其作为 Agent 工具子代理启动。
4. 子技能成功后，先结束当前步骤，再开始下一步（交接关卡）：运行 TaskList，将已完成的流水线任务设为 completed（在其描述中添加单行摘要），然后再次运行 TaskList；只有确认其状态为 completed 后，才能将下一项设为 in_progress 并继续。当前一项仍为 in_progress 时，绝不能将下一项设为 in_progress；快速运行也同样适用，只是交接时无需暂停。设计步骤只有在蓝图已写入且 architect 的一致性检查顺利结束后才算完成，而不是在开始相应步骤时就算完成。如果运行环境因子技能的某个阶段任务仍未完成而拒绝更新，说明子技能尚未完成：返回继续执行，不要跳过它。🛑 例外（交互式 customize 关卡）。 如果刚完成的步骤是 architect 的 customize 模式，不要在有编辑内容落地后立刻自动推进到 analyst。customize 步骤是一个只有用户才能结束的交互式循环（architect Step C5）；一次编辑落地并不能证明用户已完成。机械检查：TaskList 必须显示 architect 的 Design › Edit the design with you 任务已为 completed（只有当用户回答 architect 自己在 C5 提出的“完成了吗？”问题后，architect 才会将其设为完成）。只要该任务仍为 in_progress，customize 流程就仍在进行：等待 architect 提问并等待用户回答；不要再额外询问用户是否“准备好继续”。只有该任务变为 completed 后，才能推进到 analyst。
5. 子技能失败时：停止运行。失败的流水线任务保持 in_progress，并在其描述中写入 halted: <verbatim message>；其余流水线任务保持 pending。继续执行 Step 6.8，该步骤会根据这些状态显示 ✗ / ⏸。
6. 项目流水线完成后：约定文件夹工作副本已在前期创建（Step 6.1 / Step 1.1），且本次运行中的所有编辑都以它为目标，因此它与已部署内容完全一致——无需事后从根目录复制（这样做也不对，因为根目录有意保持未修改状态）。只需确认约定副本存在（只有在约定副本意外缺失时，例如直接部署跳过了 Step 6.1 的解析，才允许通过 cp 从根目录进行防御性复制）。然后继续处理下一项。 customizations.yaml 会在不同条目和不同运行之间累积；后续条目会先查阅它，再触发自己的 AskUserQuestion。这是分析器唯一能获得的跨条目信息。不存在感知多个条目的分析器逻辑。

工具调用描述规范（与分析器／架构师相同）。 管理员在设置和执行期间发出的每个 Bash 调用都有面向用户的 description 字段，会在聊天中显示为“Ran ”。不要泄露内部术语：

• ❌ 错误："Create run folder and customizations file"、"Append to customizations.yaml"、"Mkdir tmp_admin"、"Fetch URL into staging"、"yq insert at .collisions"。
• ✅ 正确："Setting up the run"、"Downloading the blueprint"、"Reading the artifact"、"Saving your choice"、"Checking earlier choices"。使用中性的日常英语，不要提及 yq／.tmp_admin／customizations.yaml。

聊天叙述也同样如此：创建运行文件夹时，最多用一个简短句子说明——“Setting up the customize pass on <slug>...”——并省略 .tmp_admin/run-<id>/ 路径。用户不需要知道被 git 忽略的暂存位置；如果用户需要调试，最终报告（第 6.8 步）会提供该路径。

6.8 最终报告

最后一个条目处理完成后（或流程暂停时）生成。首先进行运行结束检查：执行 TaskList；生成报告时，不得有任何流水线任务处于 in_progress 状态且其描述中没有 halted:。根据任务的实际状态处理此类任务：如果其输出已验证（第 4 步“验证”）→ 标记为 completed，并附上一行摘要；如果未验证 → 添加 halted: <缺少的内容>，使其报告为 ✗。然后以 Markdown 正文形式呈现，绝不使用代码围栏。条目状态取自管理员流水线任务（TaskList）：某条目的所有任务均为 completed → ✓；某个任务处于带有 halted: 的 in_progress 状态 → ✗（引用其消息）；某条目的所有任务仍为 pending → ⏸。不检查子技能自身的阶段任务。

3 个条目中有 2 个已应用到您的语义模型。

• ✓ HCM Core 已上线（23 个实体，9 个权限）。[在 Semantius 中打开 HCM Core →](<ui_baseurl>/hcm-core)
• ✗ ATS Candidate CRM 在匹配步骤失败：<分析器返回的原文消息>。
• ⏸ ITSM Helpdesk 已跳过。

文件已写入 semantius/specs/。定制内容已保存到 semantius/<org>/customizations.yaml（新增 7 个条目）。可以安全地重新运行：已应用的条目不会重复添加，解决故障后，运行会从停止处继续。如果需要支持，请参阅 .tmp_admin/<run_id>/ 中的诊断详情（每个 Agent 各有一个 diag-<agent>.log）。

快速运行暂停时，在暂停说明后添加一行：“Before it stopped, I decided N things for you; they're listed in the run folder.”（N = auto-picks.md 中的行数；references/fast-flow.md，第 6 节。）

每个 ✓ 条目都必须附带可点击的浏览器链接，与建模器《结束约定》中要求的行动号召相同（参见 semantius-modeler → "Closing Contract: clean and sticky"）：[Open <System Name> in Semantius →](<ui_baseurl>/<module_slug>)。ui_baseurl 在预检阶段通过 getCurrentUser 读取一次（例如 https://tests.semantius.app）；链接文字使用人类可读的系统名称（在第 6.3 步读取），URL 路径使用小写的 module_slug。每行开头都要使用加粗的系统名称，绝不要只写 slug。最终面向用户的说明中，绝不能用开发者斜杠命令替代此链接：斜杠命令要求 Claude Code 会话正在运行且插件以精确名称安装（独立安装并不具备这些条件），而且它展示的是漂移报告，而非用户的数据。斜杠命令是开发者／管理员使用的功能，不是部署时的行动号召。

对于所有条目均为 ✓ 的运行，删除“重新运行”和诊断日志相关行，并替换为第 8 步中的常规结束语。仅在运行失败时才显示运行文件夹路径；运行顺利完成时绝不提及该路径。

---

第 7 步：自定义协议

这是管理员和子技能如何在多次运行间共享长期策略的权威参考。架构师和分析师 SKILL 都指向本节。

7.1 为什么每个回答都是策略

架构师和分析师不会重复提出同一个问题。每个第 3 阶段／编写阶段的回答都会在规范或目录变更继续进行前，作为长期策略写入 semantius/<org>/customizations.yaml。重新运行同一蓝图、引用同一实体的同级蓝图，以及共享某个概念的全新蓝图，都会自动从这个文件中解析答案。

没有“仅限本次运行”的替代选项，没有后续的“记住了吗？”小组件，也没有退出选项。无条件地将决策视为策略。（在引导流程中跳过问题时应用的默认值，或在快速运行中获得批准后作出的选择，都不属于决策：不会写入任何内容；请参阅 references/customizations-protocol.md 7.6。）客户可以通过 git 撤销：回退 customizations.yaml 中的行，然后重新部署。Git 是审计日志；文件本身通过尾随注释记录来源（# decided <YYYY-MM-DD> during <blueprint_slug> deploy）。

只有明确取消选项（“停止，我想再考虑一下”）不会写入任何内容。取消时，文件不会发生变化。

7.2 文件位置和创建

CUSTOMIZATIONS_FILE="semantius/${org}/customizations.yaml"

在预检期间（见上文）计算。按组织划分并限定在文件夹内：文件夹名称就是组织名称，因此文件内容中不会包含 org: 字段（重复字段可能出现偏差；文件夹路径则不会）。文件夹会延迟创建；首次需要写入小组件回答时，才会创建文件，初始内容仅为 version: "1.0"。后续写入使用 yq -i 进行精确更新，以保留手动编辑和注释。

如果子技能启动时文件不存在，咨询模式（7.4）会对每次查找返回 null，并继续触发小组件；回答后写入时会创建该文件。

7.3 运行上下文（admin → sub-skill，内联）

由于 sub-skill 在主线程中内联运行（步骤 4），没有 Agent 工具输入可用于在前面添加标题。因此，admin 会在对话中、进入 sub-skill 前立即声明此固定运行上下文，sub-skill 开始运行时从中读取。前两行适用于每次调用；其余行则根据 sub-skill 和正在执行的操作而定。

run_id 也是每个 sub-skill 查找其诊断日志文件夹的方式：它会写入 .tmp_admin/<run_id>/diag-<its-own-role>.log（见“输出规范”部分），并复用 admin 的单个 run-id，而不是自行采样时间戳。无需另设 Diagnostics: 行；run-id 已包含相关信息。

Run context: run_id=run-20260527-143012
Customizations file: /abs/path/to/semantius/<org>/customizations.yaml
Interaction flow: guided                                          (every sub-skill; one of: guided | expert | fast; the flow for THIS run, Step 3)
Architect mode: customize                                       (architect only; one of: create | catalog-clone | audit | extend | customize | rebuild)
Analyst mode: reconcile                                         (analyst only; one of: reconcile | audit | extend | rebuild)
Input artifact: semantius/blueprints/<slug>-semantic-blueprint.md   (when an existing file is being operated on)
Customize flag: yes                                             (architect only when relevant; the resolved customize choice)
Deploy flag: yes                                                (modeler only when relevant)

<then the actual sub-skill input — a short plain-English instruction or the user's verbatim intent>

每个 sub-skill 的必需行：

Sub-skill	必需的标题行	备注
semantius-architect	Run context、Customizations file、Interaction flow、Architect mode、Input artifact（如果文件存在）	Architect mode 行是规范的模式信号——参见 architect SKILL.md 的步骤 0。缺少此行时，architect 会回退到自然语言检测（可能导致误分类）。
semantius-analyst	Run context、Customizations file、Interaction flow、Analyst mode、Input artifact	同理：明确指定模式优于推断。
semantius-modeler	Run context、Interaction flow、Input artifact（规格文件路径）、Deploy flag	modeler 不查询策略（规格已包含所有决策）。Interaction flow: fast 表示它知道写入操作已获得确认。

将解析后的标志映射到 sub-skill 模式——蓝图输入：

customize	deploy	Architect mode	Analyst mode	是否调用 Modeler？
no	yes	（跳过 architect）	reconcile	是
no	no	（跳过 architect）	reconcile	否
yes	yes	customize	reconcile	是
yes	no	customize	reconcile	否
yes（强制：蓝图没有 access_scope）	yes / no	customize（其第一步决定访问级别）	reconcile	取决于 deploy

将解析后的标志映射到 sub-skill 模式——规格输入：

review	deploy	Architect mode	Analyst mode	是否调用 Modeler？
no	yes	（跳过）	（跳过）	是
no	no	（跳过）	（跳过）	根据步骤 6.5 拒绝该项——无需处理
yes	yes	（跳过）	audit	是
yes	no	（跳过）	audit	否

对于从零开始的端到端构建工作流，请设置 Architect mode: create。对于克隆并部署的工作流，请设置 Architect mode: catalog-clone。

sub-skill 会从第二行导出 CUSTOMIZATIONS_FILE 并继续执行。直接调用（没有 admin 编排）时，sub-skill 会在自身的步骤 0 计算相同路径。

7.4–7.6 注册表、咨询模式以及不会写入的内容

操作细节见 references/customizations-protocol.md：

• 7.4 决策键 → yq 路径注册表——每个 Stage 3 / 创作阶段小组件的 $CUSTOMIZATIONS_FILE 路径和取值形状。它是路径的唯一事实来源；architect 和 analyst 会引用具体行（例如“Optional entity verdict”行），但绝不会自行编造新路径。
• 7.5 咨询模式（sub-skill 端）——查询策略 → 缓存未命中时调用 AskUserQuestion → 收到回答后以原子方式写入，并附带来源注释；还包括 yq 易错点（映射中的 lineComment 与 headComment）、缓存命中时的一行说明，以及询问时写入的规范（触发提示词的 skill 负责写入条目）。
• 7.6 不会写入的内容——modeler 执行前的 y/n、自由文本形式的“Other”回答、明确取消时的选项，以及 modeler 内部的任何决策。

---

第 8 步：收尾

成功执行后：

• 流水线运行：说明现在哪些内容已上线、生成的文件存放在哪里，并提供一个让用户进入产品的方式：使用最终报告中的同一个可点击浏览器链接（第 6.8 步，绝不能使用开发者斜杠命令）。以系统名称开头，而不是原始 slug；在此处显示文件路径，不要放在计划行中（快速运行时，省略文件保存位置）。示例（单项）：“完成。ATS Candidate CRM 已上线到语义模型中（6 个实体、7 项权限）。[在 Semantius 中打开 ATS Candidate CRM →](<ui_baseurl>/ats-candidate-crm)。规格文件已保存到 semantius/specs/ 下。”对于多项运行，请使用第 6.8 步的逐项链接列表。
• 仅管理员运行：说明生成了什么（列表输出、状态报告、运行状况结果），然后结束。

执行失败后：

• 原样显示失败子技能的最后一条消息。
• 根据 ../../docs/architecture.md § 6（故障模式）建议恢复路径。
• 绝不要尝试通过串联其他子技能来“修复”失败。

---

自然语言请求的路由（不使用斜杠命令）

每种表述都对应第 0 步中的六种请求类型之一（其表格列出了各类型的触发表述和流水线）；第 3 步的决策表会根据工作区状态进一步细化。以下是一些值得特别说明的对应关系：

• URL 部署的流程是 fetch → analyst → modeler；工作区蓝图的流程是 analyst → modeler；“部署该规格”会跳过 analyst（仅运行 modeler）。
• “从头开始设置 X”属于端到端构建，除非目录中存在名为 X 的蓝图，此时应进行克隆。
• “审核此文件”会根据制品类型路由到 architect 或 analyst 的审核模式（不会经过第 6 步）。
• 状态、列表和运行状况检查仅限管理员使用（第 5 步）。
• 将数据文件（CSV）导入单个实体（现有实体或新实体）不属于管理员工作，也不是流水线部署：请路由到 semantius-importer 技能。
• 移动、备份或还原模块或表（无论是否包含数据）都属于传输：请路由到 semantius-transfer 技能。

如果表述含糊，请提出一个澄清问题（第 0 步）；不要猜测。

---

管理员绝对不能做的事

• 重新决定子技能已决定的事项。 如果分析员为某个实体选择了 reuse-from <module>.<entity>，管理员不得再质疑。规范是唯一可信来源。
• 部署蓝图时跳过分析员。 建模器拒绝直接使用蓝图；将蓝图直接交给建模器属于错误。始终先经过分析员。
• 删除目录记录。 与其他三个技能一样，禁止使用 delete_*。
• 移动、重命名、覆盖、编辑或删除本轮运行中未创建的工作区文件。 预先存在的文件，尤其是仓库根目录中的任何文件，都不得触碰——这明确包括就地编辑。自定义／扩展／重建流程必须针对事先创建的约定文件夹工作副本运行（步骤 6.1／步骤 1.1），绝不能针对根目录中的原始文件。管理员唯一可以移动的文件，是本轮运行中下载的文件（从 .tmp_admin/ 移至约定文件夹）。文件名符合 *-semantic-blueprint.md／*-semantic-spec.md 模式并不能证明文件归管理员所有。请参阅步骤 1.1。
• 自动从子技能故障中恢复。 报告故障，让用户选择下一步。
• 悄悄修改内置表格。 可以添加字段，但不能替换。
• 在 customizations.yaml 中写入 org: 字段。 文件夹名称就是组织；重复字段会导致信息不一致，而文件夹路径不会。
• 创建 history.jsonl（或任何决策日志文件）。 customizations.yaml 的 Git 历史就是审计轨迹。文件内的来源注释记录每条目的日期。（每次运行的 $DIAG_LOG 并非决策日志——它会被 Git 忽略、仅临时存在，只用于诊断，绝不是事实来源。允许使用。任务列表和无任务工具时的备用清单文件属于同一类：它们用于跟踪未解决的问题和进度；答案只存放在 customizations.yaml 和产物中。允许使用。快速流程运行文件夹中的 auto-picks.md 也允许使用：它是每次运行的诊断文件，不是策略记录；参见 references/fast-flow.md 的第 5 节。）
• 在聊天中透露内部机制。 预检保护、组织探测、CLI／yq 管道、阶段转换以及技能内部术语都应写入 $DIAG_LOG，绝不能发给用户。请参阅“输出规范”一节。