用途
本技能是五阶段结构改造协议的第二阶段,用于设计目标状态的分类体系(taxonomy)。第一阶段产出的 phase-1-landscape-report.md 描述当前存在什么;本阶段的任务是定义底层结构未来将承载的概念结构——包括类别、每个条目必须携带的属性、条目之间的关系,以及谁有权查看或修改什么。
前置条件
- <working-dir>/substrate-context.md 存在。
- <working-dir>/phase-1-landscape-report.md 存在且已通过 gate 1(PASS 或 PARTIAL-with-user-approval)。
- 开始前需完整阅读这两个文件。
- 若第一阶段尚未审计,需询问用户是否先调用 structural-integrity-auditor 智能体。
四条工作流
工作流 1 — 实体分类
将资产清单中的相似元素归入逻辑清晰、普遍可理解的类别。每个实体类别需定义:
- 类名:捕捉本质的单数名词(如 Document、Ticket、Asset、Component),尽量使用底层结构自身的词汇。
- 定义:一句话说明成为该类成员的条件。
- 来自清单的示例:2–4 个属于该类的第一阶段具体资产。
- 边界情况:几乎符合但不属于的资产(以及它们应归入何处)。
- 预估数量:当前大致存在多少实例。
目标为 5–15 个类别。更少意味着分类不足(无法提供帮助的“大杂烩”类别);更多意味着过度分类(实践中会合并的类别)。
工作流 2 — 属性标准化
按实体类别定义每个条目必须携带的强制特征、标签与元数据。每个实体类别需列出属性、类型、是否必填、验证规则与默认值。例如:id(string uuid,必填,匹配 uuid 正则,创建时生成)、owner(string user-id,必填,存在于用户注册表,无默认)、created_at(timestamp,必填,有效 ISO-8601,创建时 now())、status(enum,必填,属于 {active, archived, deleted},默认 active)、tags(array,非必填,每个标签 <= 50 字符,默认 [])。
需区分:
- 通用属性:适用于所有实体类别(id、created_at、owner 等跨类通用元数据),放入共享的“通用模式”部分。
- 类别专属属性:仅适用于某一类别,放在各类别之下。
工作流 3 — 建立关系
梳理实体类别之间如何连接、依赖与交互。每个关系需说明:
- 从类 → 到类
- 基数:1:1、1:N、N:1、N:N
- 名称:从“从类”视角描述关系的动词短语(如 owns、references、supersedes、blocks)
- 方向:有向(单向)或对称(双向)
- 生命周期耦合:当“从类”实例被删除/归档时,“到类”实例发生什么(cascade、restrict、set-null、no-op)
可选包含文本或 ASCII 关系图,以实体类别为节点、关系为边。
工作流 4 — 设计访问框架
确定各层级的可见性、所有权级别与修改权限。每个实体类别需声明:
- 可见性层级:谁能看到实例(如 public / org-wide / team / owner-only)
- 修改层级:谁能修改实例(通常比可见性更受限)
- 所有权模型:单一所有者 / 共享 / 基于角色 / 委员会
- 委托规则:谁可以转移所有权及在什么条件下
- 审计策略:记录哪些变更、保留多久
若底层结构有合规要求(法律、监管、合同),需在此明确呈现。层级定义应尽可能清晰映射到现有角色/权限系统——除非现有权限模型正是要解决的问题,否则不要发明新的权限模型。
产出文件
将四条工作流合并为 <working-dir>/phase-2-taxonomy-model.md,结构如下:
Phase 2 — Taxonomy Model
Substrate: <name> Date: YYYY-MM-DD Preconditions: Read substrate-context.md, phase-1-landscape-report.md Postconditions: Ready for Phase 3 (system-environment-configuration)
1. Entity classes
[各类别定义、示例与边界情况]
2. Universal schema
[适用于所有类别的属性]
3. Class-specific schemas
[各类别属性表]
4. Relationships
[每个关系卡片 + 可选图]
5. Access framework
[各类别层级定义、所有权、审计策略]
6. Open questions for Phase 3
[明确列出推迟到环境配置的决策——例如“status 枚举是否允许各团队自定义值,还是全局枚举?”]
通过门槛(审计者将检查)
模型通过第二阶段门槛当且仅当:
- 实体类别穷尽且互斥——第一阶段清单中的每个资产恰好映射到一个类别。若有无法分类的,需显式声明“Misc”类别并给出归属规则。
- 通用模式至少有 3 个属性——至少包括:身份、所有权、生命周期/状态。
- 每个类别专属属性都有类型与必填性——没有类型或可选性未定义的 schema 字段。
- 每个关系都有基数与生命周期耦合——没有缺失这些字段的关系卡片。
- 每个实体类别都声明了可见性层级与修改层级——即使两者都默认为 owner-only 或 public。
- 存在“留给第三阶段的开放问题”部分——即使为空。
反模式
- 不要从尚未选定的框架导入属性模式。第三阶段才选择环境。第二阶段是概念性的——它描述分类法是什么,而不是哪个数据库或 CMS 将承载它。
- 不要过早合并实体类别。如果两个类别感觉相似但生命周期不同或访问层级不同,它们就是不同的类别。
- 不要定义底层结构实际不需要的属性。每个属性都是验证成本。只要求能强制不变量的属性。
- 不要设计不映射到真实主体的访问层级。每个层级必须指向可识别的用户、角色或系统——而非理论上的行为者。
另见
- references/classification-strategies.md — 常见实体分类模式
- references/access-frameworks.md — 按领域的可见性/修改层级模式