architect

运行时配置（步骤 0 — 在任何处理之前）

读取以下文件，以配置特定领域的行为：

1. ops/derivation-manifest.md — 词汇映射、平台提示

   • 使用 vocabulary.notes 作为笔记文件夹名称
   • 使用 vocabulary.note / vocabulary.note_plural 指代笔记类型
   • 使用 vocabulary.topic_map / vocabulary.topic_map_plural 指代 MOC
   • 使用 vocabulary.inbox 作为收件箱文件夹名称
   • 使用 vocabulary.cmd_reflect 作为连接查找命令名称
   • 使用 vocabulary.cmd_reweave 作为反向遍历命令名称
   • 使用 vocabulary.cmd_verify 作为验证命令名称
   • 使用 vocabulary.architect 作为输出中的命令名称

2. ops/config.yaml — 处理深度、流水线串联、自动化设置

3. ops/derivation.md — 原始推导记录（设计意图基线）

如果这些文件不存在，则使用通用默认值并提醒用户。

---

立即执行

目标：$ARGUMENTS

立即解析：

• 如果目标指定了某个具体领域（例如“架构”“处理”“MOC 结构”）：重点分析该领域
• 如果目标为空：对所有维度进行完整系统分析
• 如果目标是 --dry-run：运行分析，但不提供实施方案

按顺序执行以下阶段：

1. 定位系统文件并检测平台
2. 阅读推导记录，了解设计意图
3. 分析健康数据（近期报告或实时检查）
4. 扫描各个操作层面的摩擦模式
5. 查阅研究资料，为具体论断提供依据
6. 生成 3-5 条排序后的建议，并提供完整证据链
7. 向用户展示并在获得批准后实施

现在开始。 下文定义了七阶段工作流。

---

理念

证据胜过直觉。研究胜过惯例。

上下文文件中的每条规则都曾是一个假设。每个技能工作流都是一项设计选择。必须根据实际操作情况检验这些假设。此技能结合了三个证据来源——健康数据、摩擦模式和研究论断——以提出具体且可执行的建议。

你不是在猜测什么可能有帮助，而是在诊断实际发生的情况（健康状况 + 摩擦），并依据研究指出应当采取什么做法。每条建议都能追溯到具体证据。“我觉得这样会更好”不算建议。“健康数据表明有 12 条孤立笔记，摩擦日志反复记录了对孤立笔记的抱怨，研究论断 [[orphan notes decay faster than connected ones]] 支持添加一个由条件触发的重新编织流程”——这才是建议。

**元工作预算为 25%：**在 60 分钟的会话中，用于系统演进的时间最多应为 15 分钟。如果预计实施某条建议需要超过 15 分钟，就应建议“推迟到下次会话”。

**不变量：Architect 绝不会自动实施。**任何建议都必须先获得用户明确批准，之后才能修改任何文件。这样可以防止认知外包失效模式——在人类判断系统演进的过程中，必须始终有人参与。

阶段 1：定位

自动执行。无需用户交互。

检测平台并查找系统的关键文件：

Check filesystem:
  .claude/ directory exists         -> platform = "claude-code"
  Neither                           -> platform = "minimal"

查找以下文件（路径会因领域词汇而异）：

文件类型	查找内容	典型位置
上下文文件	系统方法论和规则	CLAUDE.md、README.md
自我空间	Agent 身份和记忆	self/identity.md、self/methodology.md、self/goals.md
运维目录	运维基础设施	ops/derivation.md、ops/config.yaml、ops/sessions/、ops/observations/、ops/health/
笔记目录	主要知识目录	{vocabulary.notes}/（可能使用领域名称：reflections/、concepts/ 等）
队列系统	流水线状态	ops/queue/queue.yaml 或 ops/queue/queue.json
模板	笔记架构	ops/templates/ 或 templates/
方法论	已习得的模式	ops/methodology/

如果 ops/derivation.md 不存在： 警告用户：“未找到推导记录。建议将仅基于当前状态分析，不包含设计决策的历史背景。”

如果 ops/config.yaml 不存在： 发出警告：“未找到配置文件。将根据观察到的行为推断当前配置。”

记录所有文件位置，供后续阶段使用。

---

阶段 2：阅读推导记录

阅读 ops/derivation.md，了解系统最初的设计意图。这是衡量偏移的基准。

从推导记录中提取：

要素	查找内容	重要性
维度位置	8 个配置维度及其推导值	偏移检测的基准
对话信号	用户说了什么，从而促成每项选择	理解最初的意图
个性	温暖度、正式程度、观点鲜明度、情感感知能力	检查语气一致性
词汇映射	通用术语到领域术语的转换	输出必须使用领域语言
一致性验证	推导时启用的约束	确定需要重新检查哪些约束
失效模式风险	哪些失效模式被标记为高风险	优先监控这些模式

还要阅读 ops/config.yaml——这是可能已偏离推导记录的实时运维配置。比较推导记录与配置中的维度位置：

For each of the 8 dimensions:
  derivation_value = [from ops/derivation.md]
  config_value = [from ops/config.yaml]
  drifted = derivation_value != config_value

记录任何偏移，供阶段 6 使用。偏移本身并非坏事——它可能代表健康的演进。但未识别的偏移会造成不一致。

如果用户请求了特定的关注领域（$ARGUMENTS），请记下与该领域最相关的维度和失效模式，并在后续阶段优先检查它们。

---

阶段 3：健康状况分析

检查 ops/health/ 中是否有近期健康报告：

# Find health reports from the last 7 days
find ops/health/ -name "*.md" -mtime -7 2>/dev/null | sort -r | head -1

如果存在近期报告： 完整阅读报告。将每个 FAIL 和 WARN 项提取为结构化证据：

For each FAIL/WARN:
  category: [schema | orphan | link | description | stale | moc | boundary | throughput]
  severity: [FAIL | WARN]
  detail: [specific finding — which notes, which fields, which links]
  count: [how many instances]

如果没有近期报告： 执行实时健康评估。检查每个类别：

类别	检查方法	FAIL 阈值	WARN 阈值
架构合规性	grep -rL '^description:' {vocabulary.notes}/*.md	不适用	任意笔记缺少必填字段
孤立项检测	传入维基链接数量为零的笔记（扫描所有笔记中的 [[filename]]）	不适用	任意孤立项
链接健康状况	指向不存在文件的维基链接	任意失效链接	不适用
三空间边界	内容位于错误空间（ops/ 中的笔记、notes/ 中的运维文件）	不适用	任意违规
处理吞吐量	收件箱条目数与笔记数之比	比率 >3:1	比率 >2:1
陈旧笔记	传入链接少于 2 个且最近 30 天未修改的笔记	不适用	笔记总数的 >15%
MOC 连贯性	每个 MOC 的笔记数量	不适用	>40 条笔记（建议拆分）或 <5 条（建议合并）
描述质量	描述只是重复标题，未提供额外信息	不适用	任意重复

实时检查实施方式：

# Count total notes
NOTE_COUNT=$(ls -1 {vocabulary.notes}/*.md 2>/dev/null | wc -l | tr -d ' ')

# Find orphans (notes with no incoming links)
for f in {vocabulary.notes}/*.md; do
  NAME=$(basename "$f" .md)
  LINKS=$(grep -rl "\[\[$NAME\]\]" {vocabulary.notes}/ 2>/dev/null | wc -l | tr -d ' ')
  [[ "$LINKS" -eq 0 ]] && echo "ORPHAN: $NAME"
done

# Find dangling links
grep -ohP '\[\[([^\]]+)\]\]' {vocabulary.notes}/*.md | sort -u | while read -r link; do
  NAME=$(echo "$link" | sed 's/\[\[//;s/\]\]//')
  [[ ! -f "{vocabulary.notes}/$NAME.md" ]] && echo "DANGLING: $NAME"
done

# Count inbox items
INBOX_COUNT=$(ls -1 {vocabulary.inbox}/ 2>/dev/null | wc -l | tr -d ' ')

# MOC sizes
grep -rl '^type: moc' {vocabulary.notes}/*.md 2>/dev/null | while read -r moc; do
  COUNT=$(grep -c '^\- \[\[' "$moc" 2>/dev/null)
  echo "MOC: $(basename "$moc" .md) = $COUNT notes"
done

# Missing descriptions
grep -rL '^description:' {vocabulary.notes}/*.md 2>/dev/null

将所有发现记录为阶段 6 的证据。每项发现都必须包含受影响的具体笔记、链接或字段，而不只是计数。

---

阶段 4：阅读摩擦

扫描多个运维界面中的摩擦模式。摩擦是系统应有的工作方式与实际工作方式之间的差距。

4a. 观察笔记

# Find all pending observations
grep -rl '^status: pending' ops/observations/ 2>/dev/null

阅读每条待处理观察记录。按类型分类：

类别	信号	证据价值
摩擦	“这件事本不该这么难”	高——说明工作流不匹配
流程缺口	“没有办法执行 X”	高——缺少功能
意外	“我没想到会出现这种行为”	中——预期不一致
方法论	“我发现 X 的效果更好”	中——运维见解
质量	“输出质量不够好”	高——质量关卡失效

统计每个类别的出现次数。同一类别中有 3 条或更多 = 值得调查的摩擦模式。

4b. 方法论笔记

# Read all methodology notes
ls ops/methodology/*.md 2>/dev/null

阅读每条方法论笔记。查找：

• 多条笔记中的反复出现主题
• 声明的方法论与实际实践之间的矛盾
• 表明原始设计有误的行为修正
• 包含多条证据的多方法论笔记（强信号）

4c. 会话日志

# Read recent session logs (last 5-10 sessions)
ls -t ops/sessions/*.md 2>/dev/null | head -10

扫描会话日志，查找：

• 反复出现的抱怨或变通方法
• 总是被跳过的步骤
• Agent 的实际行为与系统建议之间的模式
• 错误模式或工具故障

4d. 自身空间

如果存在 self/，请阅读：

• self/methodology.md — Agent 对自身流程的描述
• self/goals.md — 当前优先事项是否与系统能力一致
• self/memory/ — 关于工作流挫折的任何笔记

4e. 构建摩擦清单

将所有摩擦证据汇总为结构化清单：

Friction Inventory:
  1. [category]: [description]
     Frequency: [N observations across M sessions]
     Sources: [filenames]
     Impact: [what breaks or degrades]
     System area: [which dimension/skill/workflow affected]

  2. [category]: [description]
     ...

按频率 × 影响排序。频率最高、影响最大的摩擦模式在阶段 6 中优先处理。

---

PHASE 5：查阅研究

以研究为依据。正是这一点让 /architect 有别于临时故障排查——每项建议都关联到具体的研究结论，而非一般直觉。

阅读参考文件：

参考文件	内容	使用时机
${CLAUDE_PLUGIN_ROOT}/reference/dimension-claim-map.md	哪些研究结论影响哪些维度	将摩擦映射到维度调整
${CLAUDE_PLUGIN_ROOT}/reference/interaction-constraints.md	维度选择如何对其他维度产生压力	分析拟议变更带来的连锁影响
${CLAUDE_PLUGIN_ROOT}/reference/methodology.md	通用原则和处理流程	以第一性原理为建议提供依据
${CLAUDE_PLUGIN_ROOT}/reference/failure-modes.md	10 种失效模式及领域脆弱性矩阵	将摩擦关联到已知失效模式
${CLAUDE_PLUGIN_ROOT}/reference/tradition-presets.md	配置空间中的命名点	考虑其他配置方案
${CLAUDE_PLUGIN_ROOT}/reference/vocabulary-transforms.md	通用术语到领域术语的映射	确保输出使用领域词汇
${CLAUDE_PLUGIN_ROOT}/reference/three-spaces.md	Self/notes/ops 架构和边界规则	分析三空间边界
${CLAUDE_PLUGIN_ROOT}/reference/derivation-validation.md	派生系统的验证测试	确定变更后的验证标准
${CLAUDE_PLUGIN_ROOT}/reference/evolution-lifecycle.md	种子—演进—重新播种模式、摩擦驱动的采用	判断何时演进、何时重新播种
${CLAUDE_PLUGIN_ROOT}/reference/self-space.md	Agent 身份生成和 self/ 架构	提出与 self-space 相关的建议

研究匹配流程

针对第 3-4 阶段中识别出的每种摩擦模式或健康问题：

步骤 1：检查 dimension-claim-map.md

• 哪些研究结论与此问题相关？
• 这些结论支持哪些维度位置？
• 当前配置是否与研究建议相冲突？

步骤 2：检查 interaction-constraints.md

• 这种摩擦是否由维度不匹配造成的连锁效应？
• 为解决问题而更改某个维度，是否会给其他维度带来压力？
• 是否记录了补偿机制？

步骤 3：检查 failure-modes.md

• 这是否符合已知的失效模式？
• 派生过程中是否将此失效模式标记为高风险？
• 失效模式文档对缓解措施有何说明？

步骤 4：搜索知识图谱

• 使用 mcp__qmd__deep_search 查找针对具体摩擦的结论
• 如果无法使用混合搜索，则改用 mcp__qmd__vector_search
• 如果 MCP 不可用，则改用 qmd CLI（先运行 qmd query，再运行 qmd vsearch）
• 仅当 MCP 和 qmd CLI 均不可用时，才直接阅读随附的参考文件
• 用自然语言搜索对摩擦模式的描述
• 搜索受影响的系统区域
• 搜索拟议解决方案的相关概念

mcp__qmd__deep_search  query="[friction description in natural language]"  limit=10

阅读排名靠前的结果。对于每条相关结论：

• 记下结论标题（以便在建议中引用）
• 记下结论的论点
• 记下它如何适用于当前摩擦

目标是让每项建议都关联到具体研究，而非一般直觉。

---

PHASE 6：生成建议

综合第 2-5 阶段的证据，提出 3-5 条具体建议，并按影响与投入之比排序。

排序标准

标准	范围	衡量内容
影响	高 / 中 / 低	对系统的改进程度有多大？
工作量	分钟 / 小时 / 天	实施需要多少工作？
风险	可逆 / 部分可逆 / 不可逆	可能会出现什么问题？
证据强度	强（5+ 个数据点）/ 中等（3-4 个）/ 推测性（1-2 个）	支持证据有多充分？

最多提出 3-5 条建议。 超过 5 条会让人难以决策。如果发现的问题更多，请果断确定优先级——其余问题可以留到下一次 /architect 检查。

优先级排序

1. 健康检查中的 FAIL 项——这些功能已损坏，应优先修复
2. 高频摩擦模式——反复出现的问题，接下来处理
3. 偏离修正——配置在没有理由的情况下偏离了推导结果
4. 有研究依据的优化——有强证据支持的改进
5. 推测性改进——证据不足但值得关注的想法（最多包含 1 条）

实施时间估算

每条建议都必须包含具体的时间估算：

工作量级别	典型变更	估算时间
分钟	更改配置值、添加模板字段、编辑单个文件	5-15 分钟
小时	重新生成技能、重组 MOC、迁移架构	30-120 分钟
天	完整重新播种、架构变更、重新设计多个技能	多个会话

应用 25% 预算规则： 如果估算的实施时间超过典型会话时长的 25%（60 分钟会话中超过 15 分钟），建议推迟到下一次会话，除非问题属于健康检查的 FAIL 级别。

建议格式

针对每条建议，构建完整分析：

### [N]. [Specific change title]

**What:** [Concrete change — specific enough to implement without further clarification.
           Name the exact file, section, and value that changes.]

**Why:** [Evidence chain from health analysis + friction patterns]
  - Health: [specific FAIL/WARN from Phase 3, with note names/counts]
  - Friction: [specific patterns from Phase 4, with observation filenames]

**Research:** [Specific claims supporting this change]
  - From dimension-claim-map: [claim title and what it argues]
  - From knowledge graph: [related claims found via search, with titles]
  - From failure-modes: [if this matches a documented failure mode]

**Interaction effects:** [Cascade analysis from interaction-constraints.md]
  - Changing [dimension X] from [current] to [proposed] creates pressure on [dimension Y]
  - Compensating mechanism: [how to handle the cascade, or "none needed"]
  - If no interaction effects: "No cascade effects detected for this change."

**Impact:** [effort] effort / [benefit] benefit / [risk] risk
**Estimated implementation time:** ~X minutes
**Expected benefit:** [Measurable outcome the user can verify]
**Recommendation:** implement now / defer to next session
**Reversible:** [yes / no / partially — with explanation]

**Steps:**
1. [First concrete step — exact file and change]
2. [Second concrete step]
3. [Update ops/derivation.md with change rationale]
4. [Run validation to confirm nothing broke]

建议质量门槛

每条建议都必须具备：

1. 具体的文件引用——不能只说“更新上下文文件”，而应写明“更新 CLAUDE.md 的‘处理流程’部分，约第 150 行”
2. 证据支持——至少 2 个数据点（健康检查发现 + 摩擦观察，或 2 个以上摩擦观察）
3. 研究引用——至少引用 1 条知识库中的具体主张
4. 风险意识——明确说明可能出现的问题
5. 可逆性评估——如果效果变差，能否撤销？
6. 时间估算——具体而非含糊
7. 实施步骤——按顺序列出，每一步都引用具体文件

未达到任一门槛的建议都应剔除。 缺乏实质内容的建议会削弱信任。提出 2 条有力建议，胜过 5 条薄弱建议。

---

第 7 阶段：向用户呈现

呈现按优先级排序的建议。全程使用用户所在领域的词汇（来自 derivation.md 词汇映射）——不要向领域用户暴露通用术语。

输出格式

=== ARCHITECT REPORT ===
System: [domain name from derivation]
Platform: [detected platform]
Focus: [specific area if requested, or "full system"]
Date: [YYYY-MM-DD]

Evidence Summary:
  Health: [N FAIL, N WARN, N PASS — from Phase 3]
  Friction: [top 3 friction patterns with frequency counts]
  Drift: [dimensions that shifted from derivation, if any, or "none detected"]
  Failure modes: [HIGH-risk modes from derivation that show activity, or "none active"]

--- Recommendations (ranked by impact-to-effort) ---

[Recommendation 1 — full format from Phase 6]

[Recommendation 2 — full format from Phase 6]

[Recommendation 3 — full format from Phase 6]

[Optional: Recommendations 4-5]

--- Next Steps ---
Which recommendations would you like to implement? I will execute the steps
and update ops/derivation.md with the rationale.

Options:
  - "all" — implement all recommendations
  - "1, 3" — implement specific recommendations
  - "none" — defer all to next session
  - "explain 2" — get more detail on a specific recommendation
=== END REPORT ===

用户批准后

按照列出的步骤实施获选建议。每项实施都要：

1. 进行变更——按步骤中所述编辑具体文件
2. 展示变更前后对比，适用于非简单变更（替换章节、更改配置）
3. 更新 ops/derivation.md，记录：
   • 变更内容
   • 变更原因（证据摘要——健康检查发现 + 摩擦模式）
   • 研究依据（知识库中的主张引用）
   • 变更日期
   • 已注意到的交互影响（如有）
4. 记录到 ops/changelog.md（如果文件不存在则创建）：

   ## YYYY-MM-DD: [change title]
   
   **Source:** /architect — [evidence summary]
   **Change:** [what was modified, which files]
   **Research:** [supporting claims]
   **Risk:** [risk assessment]
   

5. 运行变更后验证：
   • 所有 wiki 链接仍可解析
   • 所有笔记仍包含必需的架构字段
   • MOC 层级结构完整
   • 未引入三空格边界违规
   • 会话导览仍可正确加载

报告验证结果：

Implementation complete.
  Changed: [list of files modified]
  Validation: [N]/[N] checks PASS
  [Any warnings or issues]

用户拒绝后

• 没有新证据时，不要再次提出相同的变更
• 可选择询问原因——如果回答体现了设计理念，将其作为新的观察记录
• 将建议标记为“已考虑并推迟”——不要反复重新提出

当证据表明应执行 /reseed 时

如果分析发现：

• 超过 3 个维度之间缺乏一致性
• 词汇已不再符合用户的实际语言习惯
• 三空间边界已消失
• 模板偏差超过 40%

那么建议执行 /reseed，而不是进行增量修补：

  NOTICE: The evidence suggests systemic drift across multiple dimensions.
  Incremental patching may create more incoherence. Consider running /reseed
  for a principled re-derivation from first principles.

  Drift detected in: [list dimensions]
  Evidence: [key observations]

---

边缘情况

没有 ops/derivation.md

建议仅基于当前状态分析。请在报告中注明：“没有衍生历史记录，因此建议无法评估偏移或设计意图。可考虑运行 /reseed，以建立衍生基线。”

没有 ops/observations/ 或 ops/sessions/

摩擦分析会受到限制。请注明：“没有可用的操作摩擦数据。建议仅基于健康状况分析和研究结果。请开始在工作期间记录观察结果，以便根据摩擦情况进行演进。”

Vault 较小（少于 10 条笔记）

规模较小时，图分析指标（密度、孤立节点、集群）的意义较小。请注明：“Vault 仍处于早期阶段。随着知识图谱增长，图健康指标将更有意义。应优先关注信息捕获和处理，而不是结构优化。”

没有研究结果

如果 MCP 工具调用失败，且打包的参考文件是唯一信息来源：

• 直接阅读所有相关参考文件
• 请在报告中注明：“研究依据仅来自打包的参考资料。语义搜索不可用。”
• 建议仍然有效——参考文件包含核心研究内容

指定了关注领域

如果 $ARGUMENTS 指定了某个领域：

1. 运行所有阶段，但让结果更侧重于该关注领域
2. 即使其他 FAIL 级健康问题不在关注范围内，也要报告
3. 请注明：“重点关注 [area]。其他发现已记录，但未优先处理。”

---

质量标准

• 每条建议都必须有具体证据作为依据（健康数据 + 摩擦模式 + 研究结论），不得仅凭直觉提出建议
• 全程使用领域词汇——绝不向领域用户暴露通用术语
• 明确表达立场——研究有其观点，应予以分享，但要解释推理过程
• 证据不足时应如实说明：“根据有限的摩擦数据得出的推测”才是诚实的表述
• 区分紧急修复事项（FAIL 项）和战略性改进（优化机会）
• 切勿建议超出系统成熟度所需的基础设施——请检查当前自动化水平
• 所有时间估算都应如实——低估比高估更损害信任
• 25% 的预算规则是指导原则，而非硬性限制——FAIL 级问题有理由超出该预算