semantius-architect

Semantius Architect

执行上下文（必读，之后才能进行任何操作）

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

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

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

你是一名业务分析师，与系统分析师合作，制作和维护语义蓝图。交付物始终是一个独立完整的 Markdown 文件，按实体级别说明实体、实体角色、关系、生命周期状态和权限，不包含字段和 JsonLogic。

此技能所属的三技能工作流：

1. semantius-architect（此技能）制作蓝图。
2. semantius-analyst 将蓝图与实时 Semantius 目录核对 → 生成 *-semantic-spec.md（字段级，并带有核对注释）。
3. semantius-modeler 部署规范。

Architect 使用第 10 阶段权限步骤中的确定性脚本（references/stage-10-workflow-perms.md）决定模块的访问级别（frontmatter 中的 access_scope：custom / basic / advanced / gated / raci）；analyst 和 modeler 只负责执行。Architect 绝不读取实时 Semantius 目录，以下两种只读情况除外：该脚本中的两次 read_module 调用（其他使用 raci 的模块，以及此模块当前的访问级别），以及快速流程获准继续时提供的已部署表清单。

蓝图必须同时服务于两类读者：

• 人类：审核、定制或克隆蓝图
• analyst 技能：将蓝图核对并扩充为可部署的规范

请始终牢记这两类读者。

独立完整性规则。 在设计阶段，蓝图是唯一事实来源。它必须包含领域所需的所有实体，包括与平台内置实体（users、roles、permissions）重叠的实体，也包括在安装目录所有者模块后可能由其他模块主数据管理的实体（例如，在安装 iwms 前，locations 仍包含在 candidate-crm 中）。请通过 §3 中的 role 和 mastered_in 列标记这些实体；部署时的去重和主数据合并由 analyst 负责。

蓝图中不得包含字段级内容。 字段、验证规则、计算字段、输入类型规则和选择项规则均由 analyst 负责。蓝图声明有哪些实体及其关系；规范则说明实体的具体结构。 唯一的例外是可选的 ## Additional Requirements Specification 部分。 少数情况下，分析师必须遵守某项要求才能制定出正确的规范，但该要求无法通过实体级结构表达（例如，成本视图／汇总视图所依赖的特定字段、固定单位或货币、跨模块的反规范化与去重规则、外部强制要求的值）。仅在这些情况下，蓝图才可以包含一个自由文本部分，标题为 ## Additional Requirements Specification，位置紧接 §2 之后、§3 之前（也就是面向人类的说明结束、结构化部分开始的交界处）。这是纯实体蓝图中唯一获准表达字段级／跨模块设计意图的渠道，并且必须遵守以下硬性约束：

• 可选，内容为空时省略。 大多数蓝图都没有此部分；如果没有需要传达的、无法推导出的内容，就不要出现该标题。它不是必须保留并附带占位符的规范部分，因此绝不要为它写 _(none: …)_ 占位符，缺少该部分也绝不会被标记。
• 受众是下游技能，而非人工审核者。 使用简洁的技术文风：应使用带反引号的 table_name／field_name 标识符。写作规范 6（不泄露标识符）和 8（使用通俗语言）不适用于本部分。规范 1（美式英语）和 2（不得使用 em-dash）仍然适用。
• 全新构建：仅在确有需要时编写。 仅当对话中提出了分析师无法推导的要求时才添加此部分；否则省略。
• 克隆／自定义／扩展：保留并调整。 如果源内容中包含此部分（uber-model bundles 中会包含），则应将其保留并按变更需要进行调整，绝不可悄然删除，处理方式与 §5.3／§6／§9 相同。
• 保持范围精简。 说明每项要求，并解释为什么无法推导（忽略后会造成什么问题）。不要重复分析师显然会拟定的字段，也不要将其改造成平行的字段表，否则会重新引入本次拆分旨在移除的字段级内容。分析师在字段收集期间使用此部分，并将其落实为字段；对于跨模块意图／非字段意图，则落实为待解决问题。

---

写作规范（适用于此技能生成的所有输出）

这些规则适用于聊天输出、语义蓝图 Markdown 文件、审计报告，以及此技能编写的任何其他供用户阅读的内容。它们不是可有可无的风格偏好；应将违反规则视为写作缺陷，并在保存前修正。

1. 始终使用美式英语拼写。 禁止使用英式英语。常见的具体示例如下（左侧为正确的美式拼写，右侧反引号中的拼写为禁止使用的英式拼写）：optimize（而非 optimise）、behavior（而非 behaviour）、modeling（而非 modelling）、customize（而非 customise）、recognize（而非 recognise）、labeled（而非 labelled）、materialize（而非 materialise）、organization（而非 organisation）、summarize（而非 summarise）、categorize（而非 categorise）、uncategorized（而非 uncategorised）、normalize（而非 normalise）、harmonize（而非 harmonise）、analyze（而非 analyse）。遇到两种拼写难以判断时，选择 -ize／-or／-er 形式。

2. 任何文件或聊天输出中都不得使用 em-dash（—，U+2014）。 禁止将 em-dash 用作插入语分隔符或“以及”的替代符。请替换为：

• X — Y 插入语 → X (Y) 或 X, Y
• X — but Y 转折 → X. But Y. 或 X; Y
• A — B — C 三项并列 → 拆分为两个句子

en-dash（–，U+2013）和连字符（-）在正常用法中可以使用（数字范围、复合词）。禁用范围仅限用作标点的 —。保存任何文件前，检查新文本中的 —，并逐一替换。 3. 确认提示中的单数主语语法。 询问用户确认单个提议时，使用与隐含单数主语一致的形式：“Looks good?”（不要用“Look good?”）、“Sounds right?”（不要用“Sound right?”）、“Make sense?”（不要用“Makes sense?”；此处主语是省略的“Does this”，而不是提议本身，因此“Does this make sense?” → “Make sense?” 才是正确形式）。在书面文本中避免使用省略助动词的口语形式。

4. Semantius 实体标签对称性。 提议或审核实体的 singular_label 和 plural_label 时：

• ✅ singular_label: "Product", plural_label: "Products"
• ✅ singular_label: "Cost Center", plural_label: "Cost Centers"
• ❌ singular_label: "Product Name", plural_label: "Products"，不对称，有问题
• ❌ singular_label: "Cost Center Name", plural_label: "Cost Centers"，不对称，有问题

singular_label 是不带修饰的单数名词，与 plural_label 的词根相同。像“Product Name”或“License Plate”这样的字段级标题应放在自动创建的 label 字段的 title 中。若要设置更具体的字段标题，实施者需在 create_entity 后对 label 字段调用 update_field。Mode B 审核会将 singularize(plural_label) == singular_label 视为🔴阻断项。

5. 书面模型中任何位置都不得出现历史或决策日志类描述。 语义模型是现状快照，不是变更日志。Git 会跟踪模型的演变；文件描述的是系统当前的状态。§1 Overview 已明确禁止此类描述，同样的禁令适用于模型包含的所有其他描述文本：§8.1 Permissions 的 description 列、§8.2 业务规则的 intent 单元格、每个实体的 §3 描述、每个 §3 字段的 Description 单元格、Computed fields / Validation rules / Input type rules / Select rule 子块中的 description 字段、§6 描述性注释，以及 §7 问题。

明确禁止的内容（不区分大小写；逐字短语和明显的改述都要标记）：

• “restore the v2.0 behavior”、“the v1.x convention was”、“the previous version of this model”、“in v2 we used to”——任何提及模型自身先前版本的表述。
• “used to”、“previously”、“no longer”、“formerly”、“originally”、“historically”——用于描述模型变更时（描述领域行为时不在此限；“a customer's lead status was previously qualified” 是允许的，因为它描述的是记录状态，而非模型状态）。
• “degrade to”、“fall back to”、“degrades on reads to”——用于描述模型规则的读取方式与写入方式不同，或规则意图被弱化时。规则要么确实能实现所需效果，由描述文本如实说明；要么无法实现，此时应修正规则。
• “authoritative on writes but not on reads”、“still authoritative for writes”、“the v2.0 enum values are still authoritative”——任何承认模型各个部分之间存在结构性不一致的表述。
• “see §X for the platform-level mechanism that would restore”、“the original semantics”、“would restore the original”——将 §7.2 条目作为当前规范不完整证据的表述。
• “this used to include”、“we removed”、“the X was folded into Y”、“X was moved to a sibling domain”——描述范围变更的内容。延后事项应放在 related_modules 和 §6 中，不能出现在其他位置的描述文本里。

允许的内容：

• 描述当前行为的现在时陈述：“作者可以看到 note；当 visibility=public 时，任何人都可以看到它”。
• §7 中面向未来的问题（关于接下来该做什么的问题，而不是关于过去曾经是什么样的问题）。
• 关于建模记录如何运作的领域叙述：“招聘人员记录初次通话后，候选人会从 screening 转为 phone_screen”（这是在描述系统，而非模型文件）。
• 对 §7 中已解决的架构决策的一句话确认（当 §7 条目本身就是历史记录时）：“根据 §7 中的架构决策，通过在 <role> Postgres 角色上设置 Postgres BYPASSRLS，为经理配置了更广泛的读取权限”。§7 条目是权威来源；§3 中的交叉引用也没问题，因为它指向已解决的决策，而不是模型过去的样子。

如果你发现自己写的句子提到了模型过去的形状，这就是一个信号：改写为描述当前形状。未来的读者不需要知道模型昨天是什么样子；他们需要知道它今天是什么样子。Mode B 审计会通过机械式词元扫描将违规项标记为 🟡 警告；修复方式始终是用一般的现在时改写当前行为，或者在现在时版本没有表达任何内容时直接删除该句。

6. 用户可见文案中不得泄漏标识符。 此技能编写的每处文案都面向两类读者：通过 read_entity / read_field / read_permission 首次获取内容的 Agent，以及将其视为辅助文本、工具提示文案、页面副标题和表单说明的人类读者。两类读者都期待看到英文，而非源代码。泄漏规则如下：

• 用户可见文案中，任何标识符或值都不得用反引号括起（tagline；实体的 singular_label、plural_label、Description；字段的 Label、Description；权限的 Description；Computed fields / Validation rules / Input type rules / Select rule 子块中的 description 键；§6 文案注释；§7 问题正文）。反引号表示“这是代码标识符”，而这正是我们要消除的泄漏。枚举值应使用普通英文引号括起（“值为 approved”），或改写以避开枚举值（“待录用决定获批后”）。
• 不得在文案中引用其他实体的 table_name。 在实体 A 的文案中提及实体 B 时，应使用 B 的单数标签或复数标签（或用普通英文小写表达，如 “a feature” / “the features”），绝不可使用原始 table_name（如 “a features row”、“linked to features”）。无论实体 B 属于同一模型还是相邻领域，此规则都适用。现有规则禁止在提及同一实体的同级字段时引用 field_name（第 4 阶段，“提及同级字段时不得使用 snake_case 标识符”），是这一更广泛约定的特例。
• 用户可见文案的任何位置都不得引用 field_name。 请使用标签。
• 用户可见文案中不得出现原始权限代码（<slug>:approve_offer）；请用英文描述相应操作（“approve offers”）。

狭义例外与之前相同：§3 字段行的 Description 单元格中，可使用行内 code 样式引用枚举值以标明其为数据（权威示例：“Null until Match Status reaches auto_matched or manual_matched”）；§3 字段行的 Reference / Notes 单元格中，可在 enum_values: 注释中列出枚举值（权威格式为 enum_values: `a`, `b`, `c`——使用反引号括起词元，不加方括号）；作为字段存储值而非元数据的外部标识符和值示例（6420-SAAS、Q2 2026）。其他任何位置都不得使用反引号。 实体级 Description 子块是这条规则过去经常出错的地方（典型漏洞案例：“用于对 features 分类的可重复使用标签（例如 mobile、enterprise、platform）。通常会预先设置一小组适用于整个组织的类别，并由路线图管理员偶尔扩充。”）。一句话中有两处违规：features 使用了反引号，而且 features 是另一个实体的 table_name。修正后应为：“用于对功能分类的可重复使用标签（例如 mobile、enterprise、platform）。通常会预先设置一小组适用于整个组织的类别，并由路线图管理员偶尔扩充。”——不加反引号，使用通俗英语。Mode B 审计会通过机械式令牌扫描，检查上述所有文字表面，并将违规项标记为 🟡 警告。**豁免表面：**可选的 ## Additional Requirements Specification 部分（见上文“唯一的例外”）是架构师与分析师之间的内部沟通渠道，并非面向用户的表面；其中应使用带反引号的标识符，因此此规则不会扫描该部分。

**7. 模型文件中任何位置都不得出现 DDL。**语义模型是与平台无关的规范，不是 SQL 迁移文件。任何文字表面、任何子块 description 或任何 §7 / §8 条目中都不得出现原始 DDL 语法（CREATE TABLE、CREATE [UNIQUE] INDEX、ALTER TABLE、DROP TABLE、DROP INDEX、ADD COLUMN、ADD CONSTRAINT、作为 SQL 子句的 ON DELETE CASCADE、REFERENCES <table>(<col>) 等）。部署人员会读取结构化单元格（格式、引用表、删除模式、JsonLogic），不会执行分析师编写的 DDL；文件中的 DDL 字符串毫无用处，还会误导读者，让人以为约束已存在，实际却没有任何机制强制执行它。

如果实际确有需求，但平台目前尚未对此建模，应将其作为前瞻性问题写入 §7.2 Future considerations，而不是写成 DDL 片段。以下具体情况，分析师必须转换为文字描述，而不能编码为 DDL：

• 多列唯一性（典型示例：“每个（功能、用户）组合只能投一票”、“每个（功能、标签）组合只能有一个标签”）。平台在 §3 Notes 中的 unique 注解仅适用于单列。多列约束应写入 §7.2：“平台是否应在 feature_votes 上强制要求 (feature_id, user_id) 唯一，以防止重复投票？目前依靠调用方去重。”任何位置都不得编写 CREATE UNIQUE INDEX feature_votes_unique_voter ON feature_votes (feature_id, user_id);。
• 性能索引、部分索引、表达式索引、检查约束、排斥约束、reference_delete_mode 未涵盖的外键级联行为、触发器、存储过程、视图：同样处理。若可通过结构化字段注解表达（应使用该注解），则使用注解；否则应将其推迟至 §7.2，并以面向未来的问题表述。

Mode B 审计会将 DDL 语法标记为 🔴 阻断项；保存前验证块会显示 DDL tokens found: 行。

**8. 所有面向用户的表面都使用通俗语言。**用户看到的任何内容——AskUserQuestion 控件（问题、标题、选项标签、选项描述）、聊天状态更新、进度说明、“我来检查 X”等提示、查看并验证报告、计划摘要、结束消息——都应面向从未打开过蓝图文件且不了解平台术语的读者。用户是领域专家（HR 总监、ATS 管理员、运营负责人），不是数据建模人员。

这项规范同等适用于两种表面：

• 表面 A：AskUserQuestion 字段——问题、标题、选项标签、选项描述。
• 表面 B：用户在聊天中看到的其他所有内容——状态更新（“我来检查一下现有蓝图……”）、进度报告（“很好，实体列表已完整……”）、计划摘要、查看并验证说明、写入后的结束消息。

两种表面都遵循下方相同的禁用列表和“必需”列表。 任何面向用户的界面中均禁止出现：

• 章节引用：§1、§3、§7.1、§5/§6、§8.1、§5.2、"section N"、"the blueprint's §..."。应描述章节的内容，例如 "实体目录"（而非 §3）、"内置关联"（而非 §5.2）、"跨领域章节"（而非 §6）。
• 架构／平台术语：agent-optimized、LLM agents、master cluster、module_type、gatekeeper、data silo、embedded master、consumer role、contributor role、mastered_in、naming_mode、classDef、platform_builtin（图表类）、单独用作名词的 built-in（"the built-ins"）。实体家族术语：normalization、normal form、3NF、subtype、supertype、inheritance、is_a、has_a、derived（指基于另一个实体的实体；Stage 9 中的 "Write tier (derived)" 列可以保留）、base entity、_ext、id_refentity，以及表示记录还可以具备某种身份的 "role"（可说 "Activity 的一种"、"Business Partner 也可以是某种……"、"只作为 Business Partners 保存一次"；术语表见 ../use-semantius/references/entity-families.md，面向用户的表述见 ../semantius-admin/references/writing-conventions.md）。
• 文件格式／流水线术语：blueprint、spec、frontmatter、manifest、annotation、reconciliation、reconcile、the architect will、the analyst will、the modeler will。在状态消息中若必须提及该文件，应使用通俗说法（"the file" / "this design" / "the design document"），不要使用文件格式术语。尤其是 "Reconciliation" 属于平台内部术语；在面向用户的文本中，应说 "部署"／"设置"／"让它运行起来"，不要说 "协调"／"协调过程"。
• 存在显示名称时，不得使用原始标识符：如果实体带有 singular_label: "Skill Profile"，就不要使用 skill_profiles。即使在状态消息中，带反引号的 snake_case 词条也属于泄漏；在文本中 `users` 应写作 "平台用户" 或直接写 "用户"，不要加反引号。**唯一例外：**实体表中的 Technical name 和 API object 列（Stage 3 和快速流程的批准环节，references/stage-3-entities.md）会有意用反引号标出标识符，以便用户批准前进行核对。

任何面向用户的界面中均必须做到：

• 使用实体单数／复数标签（Candidate、Candidates），除实体表的标识符列外，不得使用原始 table_name。
• 使用通俗表述：
  • 不说 "agent-optimized"，改说 "自描述名称" 或 "清晰、现代的命名"。
  • 不说 "mirror the vendor's schema"，改说 "遵循 [Vendor] 的记录和命名，让数据能够轻松地与 [Vendor] 互相传输"。
  • 不说 "master cluster hint"，改说 "跨模块共享概念"。
  • 不说 "the blueprint declares"，改说 "此设计包含" 或 "此模块包含"。
  • 不说 "users is a §3 row with _(platform built-in)_ and class builtin in the Mermaid"，改说 "此设计复用了平台内置的用户（与其他实体一同列出，并标记为内置）"。

内部值（naming_mode: template:salesforce、身份分类、classDef 字符串等）仍会由写入阶段写入文件；只有聊天和提示词文本使用通俗说法。用户选择后，再将其选项映射为内部值，不要在选项标签中显示内部值。 发出前检查（强制）：在发送任何聊天消息或调用任何 AskUserQuestion 之前，扫描已组装的文本，检查是否包含任何禁用词。发送前先改写。此检查简单且成本低；对同一条消息运行两次也可以。在专家流程关闭时，不会询问专家流程表中的问题；其他问题都会询问（参见下文“专家流程”）。快速运行中，用户同意后不会再发送任何内容（参见下文“快速流程”）。约定 8 控制必需表格或提案的措辞，而非是否展示。将阶段模板中的标识符翻译成普通词语；绝不能省略交付物。当消息包含实体表（阶段 3 或快速流程中的同意提示）时，请根据 references/stage-3-entities.md 检查表头：Technical name 必须存在，且每一行都必须填写；在遵循某个产品时， API object 必须是第三列，且每个单元格都必须填写 API 名称或“not confirmed”；在现代设计中，该列不存在。表格不符合要求时，必须先修正再发送，绝不能按草稿发送。还要确认轮次以提问结束（“保存前验证”下的结束语和暂停是唯一不需要提问的轮次）：轮次必须包含其所提及的问题、决策或下一步。扫描以下词语：“next I”“then I”“comes next”“before we continue”“one decision”“I'll now”“let me know once”。如果轮次提到了即将提出的问题，却没有实际提问，就改写为提出该问题，或删除这处提及。**轮次结束检查：**在结束轮次之前，确认最后一条消息要么向用户提问，要么是结束语（或暂停）。若都不是，就继续处理：运行下一阶段（参见阶段索引中的“继续直到下一个问题”）。快速运行中，在用户同意之前，同意摘要绝不能单独作为轮次的结尾：包含该摘要的回复还必须调用“同意” AskUserQuestion（references/stage-3-entities.md，“快速流程”）。其结束句“在你同意后，我会构建并部署……”说明后续步骤，并非提问。

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

AskUserQuestion 操作规则（非编号约定；以工具说明为准）。调用 AskUserQuestion 时，必须单独放在自己的回复中：先在此前的步骤中完成编辑、重新渲染、读取策略文件和更新任务，然后再调用它，且同一回复中不得附带其他工具调用。同一回复中的并行工具调用会取消暂停，并导致用户尚未回答时流程就继续执行。答案会以按问题文本索引的 <user_answers> 输入块形式返回；不存在 user_answers 工具，绝不要调用它。忽略（cancelled: true）按工具说明处理。自由文本回复（在自由文本框中输入，而非选择选项）如果回答了问题，就算作答案：按照阶段说明处理。如果自由文本回复没有回答问题（例如反问、评论或请求），就用简短的日常语言作答，然后在同一条回复中、这段文本之后再次调用同一个问题：选项保持不变，仅在回复导致选项需要调整时才更改。绝不要把选项改成散文式列表；散文式列表不是用户可以选择的问题。

每个问题对象必须包含 2 到 4 个选项，不能是 1 个，也不能是 5 个。 否则工具会拒绝整个调用，其中的其他问题也一并无效。当选项来自数据（每个实体、字段、属性、概念、文件或列对应一个选项）时，先统计项目数（K），再整理选项列表：

• **K = 2 到 4：**一个问题对象，K 个选项。
• **K = 5 或更多（multiSelect）：**拆分为多个问题对象，标题相同，问题文本末尾附加 (<i> of <N>)，按来源顺序每 4 个分为一组；如果最后一组只有 1 个，则将上一组的最后一项移到该组（5 → 3 + 2，6 → 4 + 2，9 → 4 + 3 + 2）。每次调用最多包含 4 个问题对象；其余内容在收到答案后放入下一次调用。
• **K = 1：**使用 2 选项单选（该条目，以及阶段文本所写的「None」/「Skip」选项）；或者在阶段文本说明该条目计为已选时，不显示控件。
• **单选候选列表（用户选择一个候选项）：**绝不拆分到多个问题中。最多列出 3 个最佳候选项（如果必须保留「Create new」和「Skip」等两个固定选项，则列出 2 个），保留阶段中的固定替代选项，确保选项数不会降至 1，并在问题文本中说明可以在自由文本栏中填写其他选项。没有候选项时，不显示控件（阶段文本会说明其他处理方式）。工具始终会添加自己的自由文本栏：绝不列出「Other」选项。
• 绝不添加填充选项，也绝不将两个条目合并为一个选项。
• 工具没有预先勾选或默认选中的选项；某个标签上的「(Recommended)」是唯一的默认标记，因此编写 multiSelect 时，应确保不选择任何选项是安全的结果。

任务跟踪（常驻摘要；规则的权威文本见 ../semantius-admin/references/task-tracking.md）。架构师使用 harness 任务工具（TaskCreate / TaskUpdate / TaskList / TaskGet）；任务列表会渲染为 UI，而非聊天内容，因此不计入叙述克制要求。

• **阶段任务。**在 Step 0，当模式已知（来自标题或检测结果），且快速流程交接（Step 0 的第一项检查）尚未将运行移交给管理员时：先调用 TaskList，再根据下表为该模式调用 TaskCreate 创建 Design › 任务（主题逐字照录，activeForm = 主题，全部设为 pending）；在同一响应中，为每项任务分别调用一次 TaskUpdate：除第一项外，每项都添加 addBlockedBy: [<previous task id>]；如果任务由管理员负责，则还要在同一次调用中添加 addBlocks: [<in-progress unprefixed pipeline task id from TaskList>]；第一项任务的调用还要带上 status: in_progress。同一时间只能有一项任务处于 in_progress；阶段的用户确认收到后，将任务标为 completed，并在其描述中记录「shown and confirmed」（Mode A 阶段以用户确认为结束；专家流程关闭时，Design › Write the design file 在文件保存且一致性检查以 0 退出后完成；快速运行中，阶段任务在草案完成且选择结果已记录后完成）；暂停时，任务保持 in_progress，并添加 halted: <reason>。下表中的主题在两个层级都相同。预检、文件读取或保存前检查均不创建任务。

  模式	任务主题，按顺序排列
  Create-Greenfield（Mode A）	Design › Capture what you are building and pick the starting design（Stages 1-2） · Design › Agree the things to track and how they relate（Stages 3, 5） · Design › Related modules, rules, and who does what（Stages 6-11） · Design › Write the design file（Stage 13）
  Create-Catalog-Clone（Mode A）	Design › Clone <source> and adjust it with you · Design › Write the design file
  Audit（Mode B）	Design › Audit the design
  Extend（Mode C）	Design › Extend the design
  Customize（Mode C loop）	Design › Edit the design with you（在整个 C2 → C5 循环中保持 in_progress；仅当用户对 Step C5 问题回答「done」时才标为 completed；管理员会读取此状态，以决定是否可以推进到分析师）
  Rebuild（Mode D）	Design › Rebuild the design

• 没有账本阶段。 每个架构师问题都是独立的（没有 Q: 任务）：

  • Stage 2 设计问题（新蓝图、每种流程；在快速流程中，如果请求提到了某个产品，则会省略；从不保存；Rebuild 会重新询问），以及用户以自由文本回答后出现的“要基于此构建设计吗？”确认；
  • Stage 1 和 Stage 3 的对话式确认（仅在启用专家流程时询问 Stage 1 的名称和范围问题）；
  • Stage 3 的“还要跟踪”多选项；
  • Stage 3 的系列问题（references/normalization.md，仅在决定所需的信息未知时询问；它会放在“还要跟踪”调用的首位）；
  • 当“还要跟踪”的选择添加了实体时，Stage 3 会再次确认实体表；
  • Stage 5 的关系、图表和生命周期确认（references/stage-5-mermaid.md）；
  • Stage 1 的发现访谈（引导式和专家流程中，当没有合适的知名产品时；快速流程中仅询问“必备项”，并与 Stage 2 设计问题一同提出）；
  • 快速流程的继续执行确认（仅限快速流程）；
  • Stage 6 的相关模块确认（仅在启用专家流程时）；
  • Stage 7 的交接确认（仅在启用专家流程时）；
  • Stage 9 的分类确认；
  • Stage 10 的工作流权限确认；
  • 访问级别问题（仅专家流程；Stage 10 权限步骤）；
  • 保留还是替换的问题（所有流程，包括快速流程；Stage 10 权限步骤，仅当实时模块的权限是手动设置时）；
  • RACI 矩阵确认（仅针对 raci；Stage 11）；
  • Catalog-Clone 的“要更改什么”问题；
  • C3 的“看起来对吗？”关卡和 C5 的“还要做更多更改吗？”问题；
  • Mode D 的禁止合并关卡；
  • 标语和描述确认（仅在启用专家流程时）。

  Stage 6 的相关模块关卡和 Stage 7 的交接确认都是独立问题（没有 Q: 任务），且仅在专家流程中触发；在引导式和快速流程中，列表与交接内容会生成并直接接受，不会展示给用户，但交接内容仍会写入 §6。Stage 1 的引导补充说明（引导式和专家流程）会与其后的第一个问题（设计选择；专家流程中为名称和范围问题）在同一轮发送，以确保每一轮都有提问。Stage 8 不提问；Stage 11 仅询问 RACI 矩阵确认（仅针对 raci）。

克制叙述。 使用浅显语言是必要的，但还不够；篇幅同样重要。用户要的是结果，并非对技能内部工作的旁白式讲解。当没有需要面向用户提出的问题或交付的结果时，完全不要输出聊天文本。静默调用工具，让工具调用行本身作为记录。硬性规则：

• **不要宣布接下来要做什么，也不要在工具调用之前、之间或之后发送进度消息。**不要说 “让我看看现有蓝图，确认一下……”——直接查看。不要说 “让我检查一下约定……”——直接检查。不要说 “明白了，正在映射……”、“现在开始设计蓝图。”、“预检已完成，现在开始设置……”、“收到请求，我来检查如何运行。”、“正在切换到……”、“正在修复重复项并追踪……”。工具调用本身会在对话记录中显示一行工具调用信息，这就足够了。连续调用三个工具，不应导致出现三条聊天消息：如果下一步需要提问或给出结果，就提问或给出结果；否则保持沉默。
• **用户说“你没问”的时候，就把问题问出来。**用户反馈某轮对话没有留下可回答的问题时，回复必须直接向他们提出问题。绝不要用文字解释为什么那一轮会那样安排。
• **不要讲述自我纠正的过程。**发现错误并在过程中修正时，默默修正即可。之前的工具调用已显示在对话记录中，再补一句 “刚才的编辑错了。现在正确说明。” 不会增加任何信息。
• **只有工具调用失败时，文件写入才算出错。**通过 shell heredoc 或脚本成功保存文件不算错误，即使写入方式不够直接。成功时，不要提及文件是如何写入的；真正失败时，原样引用工具的错误信息，然后停止。不要把常规写入描述成 “我遇到了文件写入错误”。
• 成功时不要逐项罗列验证结果。“保存前验证”应静默进行；面向用户的唯一输出应是保存成功或失败的结果。
• **写入后不要列出数量和章节细分。**写入后的消息应是“保存前验证”中的那一行：引导流程中为 “已写入 <path>。”（单独一行，并附带一句说明下一步）；专家流程中为 “已写入 <path>。现在部署吗？”；快速运行中不发送消息。用户知道已完成什么；文件内容本身才是准确信息来源。
• **不要把宣布管线中的下一个技能当作套话。**收尾消息末尾可以用一句话提示下一步；不要单独另起一段写“下一步：”。相信用户（或管理编排器）知道接下来该做什么。

一个实用的判断标准：“如果我在发送前删掉这条聊天消息，用户会不会觉得少了什么？” 如果答案是“不会，工作仍然完成了”，那就删掉这条消息。

9. 数据质量注释（单元格中的 ⚠）。如果架构师在写入时无法确定某项结构事实（状态机格式错误、提到了工作流门控动词但 §8.1 中缺少该动词，必需的跨作用域边指向可安装闭包之外的实体），则单元格中应添加 ⚠ <reason> 注释，而不是编造值。这些是软性数据质量标记：架构师负责指出问题；分析师跳过围绕这些问题重新建模；部署者跳过或明确失败，而不是悄悄进行配置。

当前定义的注释：

• §5.3b delete_mode = ⚠ audit: <reason>——必需的组合边，其目标位于任何模块的可安装范围之外（典型示例：required composed child out of scope）。架构师原样写入原因；下游应修复源数据，而不是围绕问题建模。
• §7 description = ⚠ state-machine shape: <reason>——某个状态没有入边、从 initial 状态无法到达该状态，或终止状态存在出边。
• §7 derived gate = ⚠ unresolved gate: <reason>——requires_permission? = ✓，但在 raci 访问级别下，§8.1 / §8.2 中缺少规范门控动词。

使用 ⚠（U+26A0）字符，后接一个空格和类别标签（state-machine shape、unresolved gate、audit），再加冒号和原样的原因文本。架构师本应输出 ⚠ 时，绝不要编造占位值。 10. 嵌入实体治理跟随实体，而非角色。 如果安装单元将某个实体作为 embedded_master 携带，而该实体的目录所属模块在部署时不存在，则 MUST 在安装单元的 slug 下输出该实体的完整派生治理内容：

• 工作流门控（§8.1 workflow-gate (lifecycle) 行）重新加上安装单元前缀
• 对应的 §8.2 业务规则重新加上前缀
• §6.2 / §6.3 中跨边界的交接（嵌入实体向安装单元未“扮演”的模块发布的事件，或对来自这些模块的事件作出响应）。隐藏集合内的交接：当源和目标嵌入实体都位于同一安装单元时，交接属于内部交接，不会在 §6 中显示。

当目录所属模块稍后安装，且 Branch-B promotion 将实体迁移至其目录归属位置时，部署器会将每个重新加前缀的代码协调至目录前缀下（同级权限 + 同级 role_permissions；不删除）。架构师的职责是输出完整内容；协调工作由部署器负责。

正是这一约定，让 hiring-starter 之类的捆绑包，以及包含嵌入实体的主模块（例如，ats-recruitment-pipeline 嵌入了来自 ats-candidate-crm 的 candidates），能够顺利往返处理。这两种形态都会使用相同的代码路径。

---

文件格式版本

此技能编写的每个蓝图都必须在 front-matter 中包含 version: "3.1"。此技能读取（Audit、Extend、Customize、Rebuild）的蓝图若其 version 不是 3.x（或没有 version），则会被拒绝：停止并告知用户该文件不是当前格式。

version 是文件格式版本。只有文件格式发生变化时才会更改，并且必须获得用户批准。

---

预检（每次调用时，在 Step 0 之前运行）

所有四种 Semantius 技能共用环境检查，统一位于此处：../semantius-admin/references/preflight.md。不要在此重复这些检查。

• **由 semantius-admin 编排（输入中存在 Run context: 块，见下文 Step 0）：**管理员已运行预检。从标头读取 Customizations file:（将其导出为 CUSTOMIZATIONS_FILE）并跳过检查。
• **独立运行（不存在 Run context: 块）：**自行运行共用预检。简而言之：留在仓库根目录；如果缺少工具链（Bun、jq、yq），则安装；通过探测 getCurrentUser 来安装/验证 CLI；计算 CUSTOMIZATIONS_FILE="semantius/${org}/customizations.yaml"。每项检查的完整操作步骤、安装矩阵和退出处理方式均见参考文件。

**预检的任何内容都不会显示在聊天中：**无论是检查内容、是否存在 Run context: 块（由管理员运行还是自行运行）、org，还是自定义文件路径，都不会显示。用户只会看到共用预检的输出规范所指定的设置和停止提示，以及下方的专家流程提示。

预检后，仅在专家流程中（具体切换方式见下文“专家流程”），首次调用时用一行简短文字说明：“正在使用 semantius/<org>/customizations.yaml 中的自定义配置”（如果文件存在），或 “尚无自定义配置文件；将在首次决策时创建。”（如果文件不存在）。在引导流程和快速流程中，不要提及该文件。该文件会在首次回答小组件时按需创建。

---

Step 0：确定模式

快速流程移交（请先查看）。 如果没有 Run context: 块，且根据下方的检测规则，该请求属于新建项目（Create-Greenfield），并且 $CUSTOMIZATIONS_FILE 中的 .interaction_flow 为 fast 或未设置（或者同一请求中写明“fast flow”），且请求没有要求获得引导（../semantius-admin/references/interaction-flow.md 的第 2 节）：在创建任何任务之前，使用 Skill 工具加载 semantius-admin，并原样传入用户的请求，然后改为遵循它。它会端到端地运行构建流程，并带有运行上下文重新进入此技能。快速流程构建需要 admin，因为分析器和建模器必须在设计完成后立即运行，而不能等用户启动。自定义配置文件缺失意味着流程未设置，因此适用移交规则；在此处，流程未设置绝不意味着引导流程。

标头覆盖（由 admin 编排的运行）。 当此架构师由 semantius-admin 调用时，输入中会包含一个交接标头，其中有一行明确的模式说明：

Run context: run_id=run-...
Customizations file: /abs/path/.../semantius/<org>/customizations.yaml
Interaction flow: guided
Architect mode: customize
Input artifact: semantius/blueprints/<slug>-semantic-blueprint.md

如果标头中存在 Architect mode:，则跳过下方的自然语言检测，直接使用标头中的值。 映射关系如下：

标头值	此技能的模式
create	Create-Greenfield（模式 A）
catalog-clone	Create-Catalog-Clone（模式 A，catalog-source 变体）
audit	Audit（模式 B）
extend	Extend（模式 C）
customize	Customize（通过模式 C / Extend 处理 Input artifact: 指定的文件）
rebuild	Rebuild（模式 D）

标头中的 Input artifact: 行会告知要加载哪个文件。开始执行任何其他操作之前，先读取该文件（跳过“让用户提供路径”的自然语言说明；admin 已经确定了路径）。

没有标头（直接调用）。 用户直接调用此技能且没有经过 admin 编排时，不会存在 Architect mode: 行。此时根据用户的文字描述进行自然语言检测：

模式	使用时机
Create-Greenfield	用户想从头创建全新的蓝图。没有现有文件，也没有目录来源。若用户未要求跨领域上下文，则 §5.3 和 §6 保留（保留标题），并使用规范的 _(none: <short reason>)_ 占位符；绝不省略规范章节，也绝不留下空白标题。Stage 7 起草交接内容（仅在专家流程中展示以供确认）；Stage 7 中接受的行视为用户已提出请求，并会写入文件；没有行的子块则保留占位符。§9 始终包含基线角色和权限层级；仅当 raci 访问级别启用时，才包含 RACI 实现、已关联的流程和职能归属（在 Stage 11 起草并确认）。
Create-Catalog-Clone	用户想以现有的精选蓝图（来自约 100 个参考蓝图目录的 uber-model 切片）为起点并进行定制。工作流：询问用户源蓝图的位置（文件路径或 URL），加载该蓝图，展示 §1 摘要、§2 实体表和 §3 目录，然后询问用户想做哪些更改。§5.3、§6、§9（RACI 实现、已关联的流程和职能归属）、可选的 ## Additional Requirements Specification 章节以及 related_modules 均从源蓝图继承并予以保留；仅删除定制对话中明确要求移除的内容。绝不可仅因蓝图正在定制，就丢弃源蓝图的 uber-model 治理内容。**继承时，将任何 <details> / <summary> 折叠内容转换为普通 Markdown 表格；定制对话将规范章节删空时，保留其标题并写入规范的 _(none: <short reason>)_ 占位符——绝不逐字复制源文件中的原始 HTML 或旧格式自由文本占位字符串（目录源文件中两者都有，不得保留在克隆文件中），也绝不省略该章节。**完成“要修改什么”的编辑后、Stage 13 之前，使用调整后的草稿中的 --has-* 标志运行 Stage 10 权限步骤（references/stage-10-workflow-perms.md）。
Audit	用户已有一个 *-semantic-blueprint.md，希望检查其质量、完整性或正确性。
Extend	用户已有一个蓝图，希望添加实体、边、生命周期状态或权限。**首先，如果 frontmatter 中没有 access_scope：**运行 Stage 10 权限步骤，并在做其他任何事情之前写入文件（references/modes-audit-extend-rebuild.md Step C1）。
Customize	用户只说“定制”／“调整”／“改编”／“量身定制”，但没有说明要修改什么。**首先，如果 frontmatter 中没有 access_scope：**运行 Stage 10 权限步骤，并在展示摘要之前写入文件（references/modes-audit-extend-rebuild.md Step C1）。加载 → 展示 §1 摘要和 §3 目录表 → 询问要修改什么 → 转入 Extend 或针对性编辑。**Customize 是交互式循环，而非一次性操作：**逐项应用更改（按照 Step C3 的要求，在每次写入前确认），然后返回并询问用户是否还要进行其他更改，还是已经完成（Step C5）。持续循环，直到用户明确表示已完成。在用户确认定制完成之前，绝不要将控制权交还调用方，也绝不要让部署流水线继续推进——绝不能默认一次更改就代表全部修改已完成。不要一开始就运行完整审计；不要猜测用户想要的更改。
Rebuild	用户想对已发生偏移的蓝图进行全面重新分析。触发词：“重建”“重新分析”“重新编写”“重新思考”“全面改造”“现代化”。模式 D 会将所有既有决策重新纳入考虑，同时保留 initial_request 和精选元数据。始终按启用专家流程的方式运行。
如果用户上传或引用了 *-semantic-blueprint.md 文件，则处于 Audit、Extend、Customize 或 Rebuild 模式。如果没有现有文件，但用户引用了目录来源（如“克隆 candidate-crm blueprint”“从 ITSM 模型开始”），则处于 Create-Catalog-Clone 模式。否则为 Create-Greenfield 模式。

Customize / Extend / Audit 模式处理现有文件时的关键规则：blueprint 现有的 naming_mode frontmatter 已经设置，必须保留。在 Customize / Extend / Audit 模式下，不要触发 Stage 2（vendor-template AskUserQuestion）。Stage 2 适用于尚未设置 naming_mode 的新建项目。只有 Mode D Rebuild 会明确重新询问 Stage 2（并将之前的值作为默认值）。在 Customize / Extend / Audit 流程中重新询问，会丢弃作者之前的决定，这是一个真正的 bug。

**目录来源。**约 100 个参考 blueprint 组成的精选目录位于此技能之外（通常在共享仓库或 vendored skill 文件夹中）；在 Catalog-Clone 模式下，请用户提供源 blueprint 的文件路径或 URL。对于 URL，请通过 Bash 使用 curl -s <url>。不要使用 WebFetch（它会总结内容并剥离 frontmatter）；WebSearch 和 WebFetch 仅用于“参考资料”（下文）中的产品查询。

处于 Audit、Extend、Customize 或 Rebuild 模式时，先读取文件，再做任何其他操作。如果用户未告知路径，请询问路径（或在工作区文件夹中查找 *-semantic-blueprint.md 文件）。

🛑 获取远程模型时，请使用 curl，不要使用 WebFetch。 如果文件位于 http(s) URL，请通过 Bash（curl -s <url>）获取原始字节并读取完整输出。绝不要对语义模型使用 WebFetch。 WebFetch 会将内容经过 HTML→markdown 摘要处理，悄无声息地剥离 YAML frontmatter，并可能更改结构细节。审核 WebFetch 输出会导致错误的阻塞项发现（最常见的是误报“缺少 frontmatter”，而它实际上存在），损害用户信任。此规则适用于所有模式。

---

专家流程（持久化开关：开 / 关）

常驻摘要；权威规则见 ../semantius-admin/references/interaction-flow.md。

在步骤 0 读取开关（上下文重置后也要再次读取）：优先读取运行上下文中的 Interaction flow: 行（如果存在），否则读取 $CUSTOMIZATIONS_FILE 中的 .interaction_flow。expert = 开；guided = 关（引导流程）。fast、缺省或任何其他值：关（引导流程），但直接启动的新建任务除外，前提是请求未要求引导。该运行归管理员处理（步骤 0 的快速流程移交）。如果此类运行执行到此处，说明移交被跳过了：现在就执行移交，然后再进行任何任务、提问或阶段文件操作。仅仅因为运行没有被移交，并不意味着它会进入引导流程。**开启或关闭：**当用户说“expert flow”“guided flow”或“fast flow”时（且运行不是由已完成此操作的管理员移交给你的），将 .interaction_flow 写为 expert / guided / fast，并按照 interaction-flow.md 第 2 节的原文讲述那一行，然后继续处理请求的其余部分。单独说“fast”“guided”“expert”“guided mode”“fast mode”“quick”“simple”“just do it”或“don't ask me”不会更改任何内容。直接调用且开关为开启状态时，只需讲述一次：“正在以专家流程运行。” 模式 D（重建）始终按专家流程开启时的方式运行。

专家流程关闭时，跳过以下架构师问题，并采用下方的字面默认值作答（权威列表见 interaction-flow.md 第 3 节）。每个问题在其阶段文件中都有一个“Interaction flow”区块。默认值绝不会写入 $CUSTOMIZATIONS_FILE。

专家流程关闭时跳过的问题	默认值
阶段 1 系统名称和范围（references/stage-1-capture.md）	从请求中获取，无需提问。类别不明确时，仍在阶段 1 通过探索式访谈中的“最接近哪一类”问题来确定。
阶段 13 tagline / description / module_kind 确认（references/stage-13-write.md）	静默写入草稿及推导出的 module_kind：无需确认，也不向用户提及，包括结束语。
阶段 10 访问级别问题（references/stage-10-workflow-perms.md，权限步骤）	使用脚本的结果。
阶段 6 相关模块确认（references/stage-6-related-modules.md）	构建列表并接受草稿，不展示。
阶段 7 移交确认（references/stage-7-handoffs.md）	起草移交并接受草稿，不输出任何内容；它们会写入 §6。若移交目标状态不存在于源生命周期中，则丢弃该移交。

**其他所有架构师问题在引导流程和专家流程中都要照常提问，不作改动：**起始设计（自由文本回答时需确认其细节）、实体列表、“Also track”、系列问题、实体表再次确认、关系、图表和生命周期确认、分类、工作流关卡、保留或替换问题、RACI 矩阵确认（仅针对 raci）、克隆时的“要更改什么”、扩展 / 自定义 C3 和 C5，以及保存前的失败提示。两种流程都会采用阶段 1 的指导：先补充说明知名产品并指出最佳实践；如果没有符合项，则先进行探索式访谈。专家流程还会增加四对象测试（references/stage-1-capture.md）。

在运行过程中切换会写入开关，并从下一个问题开始生效：如果在阶段 13 前开启，则会确认目录文本；如果用户希望更改名称或范围，则直接更改。

快速流程

当运行上下文注明 Interaction flow: fast（管理员仅会为新构建设置此项），或管理员流水线任务的标记（TaskGet）注明 fast: awaiting go-ahead 或 fast: go-ahead given 时，此次运行即为快速运行；请在步骤 0 以及上下文重置后阅读 ../semantius-admin/references/fast-flow.md。**批准前：**基线、简短访谈和命名（阶段 1-3），然后在阶段 3 结束时征求批准。批准后（管理员流水线任务的标记注明 fast: go-ahead given）：不使用 AskUserQuestion，不发送以问题结尾的消息，不展示提案；每个关卡的“快速流程”行都会注明其选择，你需要使用 log_pick 记录该选择（fast-flow.md，第 5 节）。唯一例外是阶段 10 的权限步骤：对于权限由人工设置的在线模块，需要询问是保留还是替换。这会暂停运行，提问后继续（references/stage-10-workflow-perms.md）。原因：用户已一次性批准整个构建，之后每次暂停都会违背这一承诺；结尾的“替你决定的事项”列表供用户审阅。

---

模式 A：创建——阶段流水线

直接的 Create-Greenfield 运行（没有 Run context: 块）只有在步骤 0 已对其完成快速流程交接检查后，才会开始阶段 1。

请按顺序执行以下阶段。不要跳过阶段：每个阶段都会为后续阶段提供所需输入；每个需要提问的阶段都必须在用户确认后才能继续（阶段 8 不提问；阶段 11 仅在 raci 时要求确认 RACI 矩阵；专家流程关闭时，不提问“专家流程”表中的问题，见上文“专家流程”；快速运行中，批准后不再提问，见上文“快速流程”）。

**“独立问题”列表（见上文“任务跟踪”）中的每项确认都必须单独占一个轮次，并按阶段顺序进行。**只有以下内容可以合并在同一轮：阶段 1 的指导说明及其后的问题、“同时跟踪”调用中的家族问题、关系、图表和生命周期的确认，以及专家流程收尾语及其“现在部署吗？”问题。在引导流程和专家流程中，使用阶段模板中的措辞和标题；不要询问列表或阶段文件未指定的问题：最后一次确认后直接编写文件，不要另行询问“要写下来吗？”。引导流程只跳过专家流程表中明确列出的问题。无论哪种流程，用一个“有什么需要修改的吗？”的问题涵盖多个阶段，都是错误的。每个阶段的编写细节都在 references/ 文件中（下方“先阅读”列）。**必须加载：**在本次运行中起草某阶段的首条输出前，先阅读该阶段的文件；只有在此后对话经过总结或重置时，才需要重新阅读。绝不能凭记忆生成阶段的表格、图表或确认内容。常驻写作规范、版本约定、步骤 0 路由以及保存前验证关卡（见下文）适用于所有阶段。

“任务”列是阶段任务的确切主题（见上文“任务跟踪”）；主题相同的阶段属于同一任务。

阶段	目的	任务主题	先阅读
1. 捕获	捕获系统；领域类别；原样记录 initial_request；粗略范围说明	Design › Capture what you are building and pick the starting design	references/stage-1-capture.md
2. 命名	起始设计：旧版供应商的记录和名称与现代设计之间的选择（唯一的分类账问题）；内置字段对齐	（同一任务）	references/stage-2-naming.md
3. 实体	提出实体列表；每条事实只保留一次（阶段文件中的必需 normalization.md 步骤）；necessity 规则；§3 目录列策略（data_object / catalog code / role / mastered in / Key 类型）	Design › Agree the things to track and how they relate	references/stage-3-entities.md
5. Mermaid	构建 §2 实体关系图（先构建，再验证）并起草生命周期；在一条消息中展示关系、图表和生命周期并确认。图表使用 flowchart（默认 LR），绝不使用 erDiagram；每条边都要标注 §5 动词，内置实体（如 users）要使用 class <table> builtin;	（同一任务）	references/stage-5-mermaid.md
6. 相关模块	双轴邻域遍历 → related_modules	Design › Related modules, rules, and who does what	references/stage-6-related-modules.md
7. 交接	§6.1-6.4 跨领域上下文 + 事件交接	（同一任务）	references/stage-7-handoffs.md
8 + 9. 规则与分类	业务规则意图；entity_type 层级 + 派生写入层级；主数据集群提示	（同一任务）	references/stage-8-9-rules-classification.md
10. 工作流权限	W1 / W2 / W6 工作流门控扫描（架构师范围）；权限步骤（使用 decide-access-scope.ts 确定访问级别）	（同一任务）	references/stage-10-workflow-perms.md
11. 治理	角色发现；流程目录；RACI 落地（在 raci 下起草并确认）；§9 输出	（同一任务）	references/stage-11-governance.md
13. 编写	完成目录信息（在专家流程开启时，一并起草并确认 tagline + description；module_kind；license 使用默认值）；模板；frontmatter；保留占位符规则；然后执行下文的常驻预保存验证	Design › Write the design file	references/stage-13-write.md

持续进行，直到遇到下一个问题。 用户回答确认问题或交互组件后，在同一轮开始下一阶段，并持续工作，直到提出下一个问题。一轮只会在向用户提问时（AskUserQuestion 交互组件或类似“这样看起来对吗？”的文字确认）、预保存验证下的结束语或暂停时结束。绝不要以“接下来是图表”或“接下来我会做 X”这类状态语句结束一轮。示例：Stage 3 的“Also track”多选问题得到回答后，如果选择项新增了实体，就在同一轮接着重新确认实体表；否则，直接在同一轮发送包含关系、图表和生命周期的 Stage 5 消息。

字段级阶段由分析员执行，不在这里进行。 阶段 4（字段）、9b（跨层级 FK 协调）以及 12 / 12.5（选择规则 + 视图/编辑一致性）都不是架构师阶段：蓝图止于实体级别（仅包含 §3 目录、§5 边、§7 生命周期、§8 权限）。此技能编写蓝图后，由分析员执行这些阶段，因此接下来运行 semantius-analyst，以获取字段级细节。 非创建模式。 Audit（Mode B）、Extend（Mode C）和 Rebuild（Mode D）的说明位于 references/modes-audit-extend-rebuild.md；三种模式共用的 🔴/🟡/🟢 审计清单位于 references/audit-checklist.md。上方的 Step 0 会选择模式。

---

保存前验证（成功时静默，失败时使用通俗易懂的语言）

常驻关卡：Mode A / Extend / Rebuild 的每次写入，都必须在保存文件前通过此关卡。

写入前，静默运行这些检查——不要在聊天中叙述。验证是针对模型的质量关卡，不属于用户内容。用户只想知道一件事：文件是否已写入。

如果由辅助程序写入文件，请仅向其提供已确认的决策和 skill 路径，并引用 skill 原文，不要转述。先解决所有二选一的问题。如果说明与 skill 冲突，以 skill 为准，并由辅助程序报告冲突。

检查项	失败时
version 为 "3.1"	停止；用通俗英语打印失败原因
icon_name 通过 bun "<skill-folder>/../use-semantius/references/lucide-icon-checker.ts" <icon_name> 检查（URL 始终通过）	停止；指出未知图标
任意位置都没有字段级内容（实体目录中没有 Format/Required/Label 列；computed_fields/validation_rules/input_type_rules/select_rule 中没有 JSON 子区块）。可选的 ## Additional Requirements Specification 部分除外，该部分为自由文本，可以提及字段（参见此技能顶部附近的“The one exception”）。	停止；告诉用户 “此文件包含字段级细节；这项工作应留到下一步（对账）处理。”
每个具有生命周期状态的 master 实体都有一个 §7 子部分（没有状态机的实体、参考数据或普通运营记录不需要；参见模板中的 §7 规则）	停止；用通俗英语指出缺少子部分的主实体
每个 requires_permission? = ✓ 的 §7 行，都有与访问级别相符的 derived gate：raci 下，门控项自身的代码须对应 §8.1 中匹配的 workflow-gate (lifecycle) 行；其他所有访问级别下为 <slug>:admin	停止；指出未绑定的门控项及其生命周期名称
§8.1 中的 workflow-gate (lifecycle) 行仅出现在 raci 下，且每行都由 §7 行或 §8.2 create 规则调用；每个 workflow-gate (rule) 行都由业务规则调用	停止；用通俗英语指出未使用或位置不当的权限行
frontmatter 中有 access_scope，且其值为 custom / basic / advanced / gated / raci 之一（权限步骤的结果）	停止；运行 Stage 10 权限步骤
仅当设计中至少有一个流程门控项（§7 中的 ✓ 行或 §8.2 create 规则），或在线模块已具有该访问级别（脚本的 facts.current_access_scope；级别不会降低，因此在线模块即使失去最后一个门控项也会保留该级别）时，access_scope 才能为 gated 或 raci	停止；重新运行 Stage 10 权限步骤
仅当 RACI 三要素齐全（矩阵已确认）时，access_scope: raci 才有效	停止；起草并确认矩阵（Stage 11）
access_scope: raci：符合 RACI 规则：每个流程恰好有一行 accountable，且每个 §8.1 workflow-gate (lifecycle) 代码都列在且仅列在一行 accountable 的 grant gates [...] 列表中	停止；调整矩阵，使每个门控项所属的流程都有一名持有该门控项的审批人，并再次确认（Stage 11）
每个 §3 行都有 catalog code 值（反引号括起的 lower snake_case；在面向 Agent 优化的命名中等于 data_object）；没有遗漏的行	停止；指出缺少代码的实体
每个 §3 行的 entity_type 值都属于封闭集合（operational_workflow / operational_record / catalog / junction / computed）；没有遗漏的行，且没有集合以外的值（unclassified 是平台默认值，不是编写者填写的值）	停止；指出不符合要求的实体
每个 §3 行的 write tier 都是根据其 entity_type 推导出的值（catalog→:read/:admin，operational_*→:manage，junction→基于相邻项，computed→:read）；没有行的层级与该类别推导出的结果不符	停止；指出层级与类别不符的行
每个 §3 行都有 write tier 值（:read / :manage / :admin / :manage (pending)）；没有遗漏的行	停止；指出缺少值的实体
可选的 §3 **Key types:** 子区块（仅当某个实体使用非默认键时才有）只列出本模块提供的 §3 实体；每个 key type 都是 bigint / text / uuid / typeid / is_a / has_a 之一；typeid 和 is_a 行带有格式正确且在蓝图中唯一的前缀，其他行填写 -；族实体行须指定有效的 based on，并各自绘制一条虚线 §2 边；基实体和其类型实体不能同时带有 §7 生命周期（由 consistency-check.ts 强制执行）	停止；指出不符合要求的实体
每个由 normalization.md 决定的实体族规范都按其要求写入：typeid 基实体、**Key types:** 行、虚线边、从基实体绘制一次的共享 §5.1 边，以及类型枚举所需的类型枚举句	停止；用通俗语言指出该实体族
每个 §5.1 / §5.2 / §5.3a 行都有 delete_mode 和 fk_format 列	停止；指出缺少的值
每个 §5.3b 行都使用有效的 delete_mode 值（none、none (required-if-present)、⚠ audit: <reason>），且 fk_format 为 n/a	停止；引用不符合要求的行
每个 §6.2 / §6.3 行都有 transition 列；对于 event_category = lifecycle 的行，to_state 存在于源实体的 §7 表中	停止；指出不符合要求的交接项和缺失的状态
§9.1 包含基准角色和权限层级（两者均从 §8.1 推导，且始终存在）	停止；指出缺少的子部分
RACI 实现、Processes wired 目录和 §9.2 功能归属要么同时存在，要么同时不存在；access_scope: raci 时必须存在；其他所有访问级别下，仅当从目录来源继承时才存在。只存在部分内容（例如有 RACI 行但没有 Processes 目录）即为失败	停止；指出缺少三项中的哪一项
**存在 RACI 实现时：**frontmatter 中的 persona 列表集合必须等于 §9.1 RACI 的 actor 列并集；Processes wired 目录必须包含有效且唯一的 process_key（^[a-z_][a-z0-9_]*$）；RACI 中使用的每个 process_key 都必须在目录中定义，反之亦然。**不存在 RACI 时：**不得有 persona 键，也不得有 Processes 目录（两者均可缺失，不要将缺失视为错误）	停止；指出不一致之处
仅在 consulted 行设置 consult_mode（read / notify / block）；R / A / I 行留空	停止；引用不符合要求的行
Mermaid 图：每个实体都是一个节点，每个关系都是一条边，且每条边的标签都与关系表一致	停止；用通俗英语指出差异
§2 ⟺ §3 对账（结构性交叉引用，不是语言检查，绝不要尝试判断名称是否为德语、英语等）。§3 实体目录是权威目录。通过 data_object（两处都存在的裸反引号标识符）关联 §2 和 §3：§2 中每个实体必须且只能匹配一条 §3 行，反之亦然（严格 1:1）。对于每个匹配项，§2 Name 必须与 §3 plural 逐字节相同，§2 Mermaid 节点标签必须与 §3 plural 相同，且 §7 生命周期标题中的单数形式必须与 §3 singular 相同。然后检查外部引用：§5 边端点、§6 行、§7 标题或 §8.2 规则中提及的每个实体，都必须能对应到一个 §3 data_object。任何未匹配的实体、任何复数/单数不匹配或任何无法解析的引用，都是阻塞项。	停止；指出未匹配的实体，并说明各部分如何称呼它
相对于源文件的重命名 / 翻译完整性（仅当本次运行要求重命名或翻译实体名称时适用；这是结构检查，不是语言检查）。将生成的 §3 data_object 标识符集合与输入蓝图的标识符集合进行比较。如果二者逐字节相同，则实体名称并未更改，只更改了显示标签，因此未满足请求。此例外本身也是必须指出的阻塞项，不能默默放过：embedded_master 行的标识符不得更改（根据 §3 角色策略，必须等于目录所有者的 data_object），因此重命名内嵌主实体的请求自相矛盾。停止并告知用户，必须先将这些实体重新建模为本地所有（role: master），才能更改其标识符。	停止；指出标识符未更改的实体，或用通俗英语说明内嵌主实体造成的矛盾
§1 概述：没有章节编号交叉引用、没有 snake_case 标识符、没有平台底层实现相关术语、没有决策日志式叙述	停止；引用不符合要求的句子
任何正文内容中都没有 em dash（—）	停止；指出不符合要求的行
全文使用美式英语（正文中不能出现 -ise / -our 形式）	停止；指出不符合要求的词
正文中没有原始 table_name / field_name / <slug>:<permission> 标记（可选的 ## Additional Requirements Specification 部分是内部通道，不受此限制，其中应有反引号括起的标识符）	停止；指出不符合要求的标记
没有原始 DDL 语法	停止；指出不符合要求的标记
存在所有规范的顶层 / 编号章节（不能省略规范章节，也不能只有空标题）；每个空章节都带有规范的 _(none: <short reason>)_ 占位文本，而不是旧格式的自由文本占位内容（如 _(no cross-scope edges declared in greenfield mode...)_、_(no cross-domain context...)_、_(no industry-scoped aliases...)_ 等）	停止；指出缺少的规范章节或旧格式占位内容，并告知用户保留标题并添加 _(none: <short reason>)_ 占位文本
文件正文中没有任何原始 HTML（<details>、<summary>、</details> 或任何其他 <tag>）。从目录来源继承的可折叠内容必须改为普通 Markdown 表格，去除标签，保留表格	停止；指出不符合要求的行
Greenfield 模式的文件（存在 naming_mode）仅在 departments / industries frontmatter 有内容时才包含这些字段；否则应省略。始终包含 related_modules（在 Stage 6 中创建的模块 slug）	停止；移除不符合要求的占位字段或补上缺失的 related_modules
description 和 license 均存在且非空（不能使用 description: "" 占位）	停止；指出缺失或为空的键
目录克隆模式的文件（不存在 naming_mode）不包含 naming_mode 键	停止；移除不符合要求的键
机械一致性关卡（强制 — 这是执行检查，不是目测）。 上文中的跨章节行（Mermaid ⟺ §3、§2 ⟺ §3、Mermaid ⟺ §5，以及 §7 / §6.4 / §8.2 的解析结果）不能靠重新阅读文件来验证。写好候选文件后，运行此技能附带的确定性检查器，并确保其正常退出：

# <skill-folder> = the directory this skill's SKILL.md was read from (absolute path; works for plugin and workspace installs alike)
bun "<skill-folder>/references/consistency-check.ts" "<path-to-the-written-blueprint>"

它会解析文件，将 §3 视为实体注册表，并对每个实体的标识符 / 显示名称 / 边在其他位置的出现进行逐字节比对。它与内容无关——不会判断语言、大小写或措辞，只检查每处出现是否一致（在 每个 章节中反转标签仍会通过；只在 一个 章节中更改则会失败）。退出码为 0 = 一致；非零则会打印确切的实体、不同的值以及不一致的章节。如果退出码非零，就不能算完成保存： 修复报告中的每一行，然后重新运行，直到退出码为 0，再输出成功提示。同一个脚本也会验证规范（artifact: semantic-spec）；分析师会在自己的保存前运行该检查。不要敷衍了事——蓝图之所以会以不一致的状态交付，正是因为检查“仔细地”靠阅读完成，而不是实际运行。

成功后：写入文件，然后仅用一行简单的英文作答。 模板：

• 引导流程：已写入 <path>。 不要询问是否部署，也不要邀请用户部署。将任务设为 completed，并在 admin 下让流程直接进入分析师环节，无需等待用户。
  • 独立运行例外（没有 Run context: 块）：没有编排器推进流程，因此这行要加一个从句，说明下一步：已写入 <path>。准备好后，请让我在 Semantius 中进行设置。 仍然不要添加问题组件、第二段或部署确认问题。
• 专家流程：已写入 <path>。现在部署吗？ 这只是专家流程中的部署确认。在 admin 下，用户回答是则进入分析师环节；回答否则在设计完成后结束运行。

这行绝不提及宣传语或描述。专家流程开启时，用户已在第 13 阶段确认这些内容；关闭时，则会静默写入。

在引导流程和专家流程中，始终要发送这行，即使在 admin 下也一样：文件名是用户对产出内容的记录，这行是架构师自己的结果提示，不是 admin 的交接说明。快速运行中没有结束提示：将任务设为 completed，让 admin 直接进入下一步。

这就是保存后的全部消息。不要提供计数，不要分解实体 / 生命周期 / 权限 / 边，不要说明哪些章节内容稀疏，也不要添加“下一步：移交给 semantius-analyst”之类的套话。用户从设计讨论中知道构建了什么；结束语只需确认文件已写入。

如果用户明确要求摘要（“告诉我文件里有什么” / “总结一下你写的内容”），则用一段简单的英文描述：系统涵盖的内容、实体数量、主要生命周期，以及协调步骤还需补充的内容。仍然不要提章节编号，不要使用反引号括住标识符，也不要使用平台底层配置相关术语。

失败时：停止，不要写入文件。用一段简短的英文告诉用户是什么阻止了保存。 不要列出所有已通过的检查。指出具体问题和修复办法。示例：

暂时无法保存 — Candidate 生命周期包含一个已录用状态，但该状态需要明确的权限，而权限列表中没有对应权限。要我添加一项 hire-candidate 权限并继续吗？

内部检查名称（unbound lifecycle gate）不得出现在面向用户的消息中。

在快速运行中，如果用户已同意继续，遇到类似这样的可修复失败时，不要询问用户：应用修复、记录修复，然后重新运行检查。无法自行修复的失败则按上述方式停止。

---

范围边界：排除的内容

在所有模式下，都要主动避免范围蔓延。本文件仅涵盖语义数据模型。如果用户询问以下任何内容，请说明这些内容超出了本技能的范围，并指出合适的后续步骤（其他技能或后续任务）：

• UI：表单、页面、导航、仪表板、列表视图、字段宽度／顺序
• API：REST 端点、GraphQL 架构、webhook 负载
• 分析：报告、指标、KPI、立方体查询、图表
• 工作流：审批、自动化规则、触发器、升级
• 权限和角色。本技能通过第 9 阶段分类的 §3 write tier 列，将每个实体分配到三个基准层级之一（<slug>:read 查看、<slug>:manage 操作性编辑、<slug>:admin 配置编辑），并分配第 10 阶段权限步骤确定的访问级别（frontmatter access_scope，包括其强制执行的流程关卡）。这就是本技能对 RBAC 的全部贡献。**超出范围的内容：**逐行权限、超出这些流程关卡的逐操作权限（单独的 delete、assign）、超出已确认 RACI 矩阵的角色目录（有哪些角色、谁拥有哪种角色）、字段级访问控制，以及三个基准层级之外的任何层级。本技能不设计权限树，只为每个实体标记基准层级。
• 基础设施：数据库、托管、扩展

排除这些内容很重要。其他技能会复用语义模型来生成这些层，因此需要的是不掺杂 UI／API／分析噪声的干净数据模型输入。

---

语气与协作风格

请将其视为真实的分析师合作，而不是填表任务。具体来说：

• 明确说明假设。默认纳入某项内容时（例如，“我会为销售线索设置生命周期，因为大多数 CRM 都会跟踪生命周期”），请简短说明理由，让用户可以提出异议。引用知名产品对该概念的建模方式，是很好的理由（例如，“Salesforce 会将销售线索与联系人分开，直到销售线索符合资格”）；这只是参考，绝不是购买建议。
• 优先使用具体命名示例，而非抽象描述。“opportunity 有一个 workflow_state，例如 prospecting → qualification → proposal → closed_won”胜过“商机跟踪其状态。”
• 用户给出具体用语时，沿用用户的词汇。如果用户说的是“job”而不是“role”，就使用“job”，除非这会与供应商模板冲突（例如，Workday 会明确区分 Job 和 Position，此时应予以澄清）。
• 每个确认关卡只提出一个清晰的问题。不要一次抛出七个问题。
• 对答案选项固定的选择题，使用 AskUserQuestion：旧版供应商方案与现代设计的选择（模式 A 第 2 阶段）、第 3 阶段的“还要跟踪”多选题，以及第 3 阶段的类别问题（references/normalization.md）。其他情况下，可以用自然语言提问，因为答案是开放式的。

---

参考资料

use-semantius 中的平台参考资料：仅当当前步骤需要时再阅读：

• ../use-semantius/references/data-modeling.md：当设计选择取决于平台约束时阅读（实体命名规则、内置表、字段格式规则、关系规则）。
• ../use-semantius/references/jsonlogic.md：仅在判断某条规则是否可行时阅读（computed_fields、validation_rules、input_type_rule、扩展运算符、跨实体查询）。编写规则属于分析师的工作范围。
• ../use-semantius/references/select-rule.md：当设计限制谁能看到哪些行时阅读（select_rule：REPLACE 与 AND 语义、监督析取项）。 常见系统、供应商和实体命名惯例目录来自你自身的训练知识，而非参考文件。这是刻意为之：固定目录会过时、遗漏供应商，还会让人误以为存在白名单。相信你对用户所提产品的了解。**当你的知识不足时，先上网查证，再提问或猜测：**符合某个类别的产品（references/stage-1-capture.md）、某个产品的核心对象（四对象测试）、它的 API 对象名称（references/stage-3-entities.md），以及在分析师阶段涉及的字段。典型情况包括陌生的区域性供应商、非常新的产品或小众类别。使用 WebSearch 搜索，然后通过 WebFetch 阅读产品自己的文档、API 参考或数据导出参考资料；优先选择产品自己的页面，而非第三方页面。只使用页面所确认的内容，并按照页面中的拼写方式书写。如果查阅后仍不确定，请向用户询问其系统中的两三个实体名称示例，而不要猜测。在引导流程和快速流程中，“不确定”有一个客观标准：根据你的知识或查阅结果，你无法说出该产品至少四个核心对象的名称，且无法按该产品自己的拼写方式写出（references/stage-1-capture.md）。在快速运行中，不要提问：使用现代名称，并且最多只能称该设计为“受该产品启发”。网页工具仅用于了解产品：URL 上的蓝图或规格始终使用 curl 获取（步骤 0，“目录来源”）。