在软件系统的工程化迭代中，提示词工程向工程化系统的演进往往伴随着目录结构与运行时机制的重塑。

回顾过去的实践路径：数月前，我们将 VS Code Continue 的松散提示词体系迁移至 Antigravity IDE 的全局工作流（global_workflows），为各个角色确立了标准作业程序（SOP）；几天前，面对跨版本配置漂移与排障死循环，我们进一步在工作流内部建立了 L0-L3 分层核验与双轮熔断机制。

然而，随着系统承载任务复杂度的增加，早期的“全局工作流平铺”机制逐渐触及底层瓶颈。近期，Antigravity 定制体系正式废弃 global_workflows，确立以 Skills（技能） 与 Rules（规则） 为基准的现代化定制架构。

这场架构升级不仅改变了文件的物理组织形式，更引申出一场深入的工程权衡：当 Skill 架构赋予了开发者挂载独立执行脚本（scripts/）的能力时，我们是否应该顺理成章地将所有认知角色（如 /verifier、/researcher、/analyzer）全部脚本化？

1. 瓶颈解构：全局工作流平铺机制的退化路径

要理解架构演进的驱动力，需要还原旧机制在复杂交互场景下的微观退化过程。

从全局工作流平铺到模块化Skills的架构演进

1.1 上下文预算的静态消耗与信噪比稀释

在旧的 global_workflows 机制下，所有工作流文件平铺存放在配置根目录下。当会话启动时，大量关于写作范式、文档编译、代码审计的长篇规则文档会被整体或大段引入系统提示词。

这导致了系统性的资源浪费：在进行简单的目录巡检或单函数重构时，模型上下文中充斥着 Typst 排版规则、学术论文评审维度以及行业分析报告模板。这种底噪不仅消耗宝贵的上下文预算，还会在长上下文注意力分配中稀释模型对核心代码逻辑的关注度。

1.2 纯文本提示词对确定性计算的表达无力

大语言模型的强项在于语义抽象、上下文推理与多模态联想，弱项在于严密的二进制字节处理、深度嵌套的 XML AST 遍历以及多媒体元数据标签封装。

在旧体系中，处理诸如“逆向解包 Word XML 并提取样式指纹”、“计算人声音频的时间戳逐字对齐”等任务时，系统只能依赖长篇提示词命令模型模拟执行算法。这造成了两个结果：提示词篇幅膨胀，生成结果却频繁出现属性遗漏或格式语法错误。纯文本提示词无法替代确定性计算代码。

1.3 跨项目环境隔离与继承机制的缺失

全局工作流缺乏分层的覆盖优先级。当面对异构项目（例如前端 WebAssembly 仓库与纯文档编译仓库）时，如果不同项目需要对 /builder 或 /verifier 实施差异化的构建审查标准，开发者只能反复手动修改全局配置文件，无法实现“全局默认规范 + 项目私有特化”的平滑继承。

2. 架构范式转变：Skills 的三大微观支柱

为了化解上述结构性矛盾，系统完成了从 config/global_workflows/ 向 config/skills/ 的物理迁移与标准化重构。现代 Skills 架构依托三大支柱重构了运行管线：

2.1 渐进式披露（Progressive Disclosure）

渐进式披露通过两阶段加载机制解决了上下文底噪问题：

  • 阶段一：轻量级索引驻留
    在 Agent 会话初始化阶段，系统仅扫描各 Skill 根目录声明的 YAML Frontmatter（仅提取 name 与 description），将其作为功能索引挂载至系统上下文中。无论系统积累了 20 项还是 100 项技能，初始化开销始终稳定在 $O(1)$ 的常量级别。
  • 阶段二：运行时按需展开
    仅当用户输入对应的显式指令（如 /chinese-insight-writer）或任务意图与技能描述发生高置信度匹配时，Agent 才会按需读取该 Skill 下的 SKILL.md 全文，并按需执行配套脚本。未被调用的技能不会对当前对话产生任何注意力干扰。

2.2 能力与资产自包含（Self-Contained Encapsulation）

新架构将技能从单一文件升级为模块化目录包：

config/skills/<skill_name>/
├── SKILL.md                 # 核心提示词契约与行为规范（含 YAML Frontmatter）
├── scripts/                 # 可执行 Python/Shell 辅助脚本（确定性计算引擎）
├── references/              # 官方规范切片、API Schema、SSOT 来源
├── resources/               # 模板文件与静态预制资产
└── examples/                # 少样本样例（Few-shot prompts/outputs）

这种拓扑建立了明确的劳动分工：自然语言提示词专心定义推理框架、边界约束与审查门禁；复杂的数据清洗、AST 转换、正则匹配与外部系统调用则交由 scripts/ 下的独立代码执行。

2.3 严格的五级优先级覆盖链条

为了支持项目级隔离，系统确立了清晰的解析顺序：

\[\text{Workspace Project (.agents/)} \succ \text{Declared (skills.json)} \succ \text{Global (config/skills/)} \succ \text{Built-in}\]

当某个研发仓库在根目录下的 .agents/skills/verifier/ 定义了该项目特有的校验规范时，该定义自动覆盖全局默认的 config/skills/verifier/，从架构层面根除了多项目规则冲突的隐患。

3. 资产全景：基于计算确定性的四层拓扑分布

完成 14 项原生工作流迁移与现有工具整合后，配置中心沉淀了 21 项独立技能。结合计算确定性（Algorithmic Determinism）与认知抽象层级（Cognitive Abstraction）两个维度，全量资产划分为四大象限层级：

基于计算确定性与认知抽象度的四层技能拓扑

全量资产呈现出梯度鲜明的职责分工：

  • Tier 1（6 项）：专注于非文本、AST 树或多媒体流的底层处理，内部封装了完备的 Python 脚本与 CLI 接口。
  • Tier 2（4 项）：承担编译构建与清洗流程的编排，通过工作流串联调用底层 Tier 1 引擎。
  • Tier 3（6 项）：覆盖通用软件研发的全生命周期，构成系统的元认知中枢。
  • Tier 4（5 项）：面向深度创作与战略研报，提供纯粹的逻辑演进与结构化思维范式。

4. 深度论证：通用元认知技能的“脚本化陷阱”

在目录完成标准化后，工程团队面临一个核心抉择：既然 office-parser 和 ai-lyrics-aligner 借助脚本取得了显著的准确率飞跃，那么作为元认知中枢的 /verifier（验证者）与 /researcher（调研者），是否也应当编写专属的 scripts/ 工具？

经过对执行链路与维护成本的全面审计，架构决策记录（ADR）明确给出了否定结论。这一推论源于三处关键的工程冲突：

4.1 /verifier 的多态性冲突与能力冗余

尝试为全局 /verifier 编写测试或静态分析脚本，会迅速陷入跨环境多态性困境（Polymorphism Dilemma）：

  1. 项目技术栈异构性断层
    全局配置服务于不同的工作区。若在全局 verifier 中预置 run_tests.py，脚本该调用 pytest、cargo test、go test 还是 npm test？一旦将其硬编码为某种语言环境的 Runner，当用户在 Typst 文档仓库或 C++ 项目中调用 /verifier 时，全局脚本会立即因依赖缺失或命令不兼容而崩溃。
  2. 原生运行时能力的重叠
    Agent 原生具备 run_command 工具，拥有动态检测当前工作区配置（如解析 package.json、Cargo.toml）并直接调用宿主机 CLI 的能力。在 Skill 内部用 Python 对这些系统命令进行一层浅包装，属于增加系统复杂度的反模式。
  3. 定位错位风险
    /verifier 的核心壁垒在于思维审查的独立性。它负责执行自底向上的 L0（Schema）到 L3（业务逻辑）分层诊断，以及在两轮排错失败后触发熔断、清零已有假设。这种高阶元认知审查无法被静态脚本所承载。

4.2 /researcher 的生态覆盖与维护腐烂

为 /researcher 编写抓取脚本同样是不合理的演进方向：

  1. 内建工具与插件生态的充分覆盖
    在系统底层，内建的 search_web 与 read_url_content 已经覆盖了通用网络检索与网页抓取需求；在专业学术领域，系统已挂载的 science 插件提供了覆盖 ArXiv、PubMed、EuropePMC、ChEMBL、OpenAlex 等十余个专业数据源的完备工具链。额外编写脚本只会产生无意义的功能重叠。
  2. 环境腐烂（Maintenance Rot）风险
    针对第三方网页的自定义爬虫脚本极易受到反爬策略、DOM 结构重构、接口鉴权变更等不可控因素的影响。将这些易碎的抓取代码沉淀在全局配置中，会显著推高配置体系的维护成本。
  3. 规范重于抓取
    /researcher 的核心价值在于建立证据分级准则（Level A 官方标准 / Level B 学术文献 / Level C 社区讨论）与事实假设分离模型。它的职责是指导模型如何辨别信息真伪，而非充当底层爬虫。

4.3 /collector 的克制落地：唯一的轻量辅助例外

在全量 Tier 3 元认知技能中，/collector 是唯一被允许并落地轻量脚本的特例。其引入的 scripts/preview_tree.py 具有极具克制的工程特征：

  • 零外部依赖：仅依赖 Python 标准库实现，杜绝因环境缺少三方包导致的运行失败；
  • 服务于全局约束：通过受限递归深度与字符截断，在数百毫秒内输出目录拓扑，并精准标记各类技术栈的 SSOT 基准文件（如 package.json、Cargo.toml、main.typ）；
  • 落地“预览优先（Preview-First）”原则：切断了大语言模型在探索陌生仓库时全量读取无关文件造成的 Token 浪费。

5. 治理规约：准入数学判定模型与“三不原则”

为了避免后续技能开发陷入“盲目加脚本”或“过度提示词化”的两个极端，我们确立了一套兼顾算法特征与维护成本的准入控制机制。

5.1 脚本准入数学模型

\[\text{AllowScript} \iff \frac{\mathcal{D}_{\text{algo}} \times \mathcal{C}_{\text{AST/Binary}}}{\mathcal{P}_{\text{poly}} + \mathcal{M}_{\text{env}} + \mathcal{O}_{\text{native}}} \ge 1.0\]

模型各因子的物理含义与取值边界如下：

  • $\mathcal{D}_{\text{algo}} \in [0.0, 1.0]$：任务算法确定性。二进制标签读写、公式几何计算为 1.0；思维审查、架构权衡为 0.1。
  • $\mathcal{C}_{\text{AST/Binary}} \in [1, 10]$：非文本或树状结构复杂度。纯 Markdown 文本为 1；嵌套 XML 压缩包、Pandoc AST 管道为 8~10。
  • $\mathcal{P}_{\text{poly}} \in [1, 10]$：跨语言与项目多态性成本。专用多媒体引擎为 1（与开发语言无关）；通用测试校验为 8~10（高度依赖具体项目技术栈）。
  • $\mathcal{M}_{\text{env}} \in [1, 10]$：运行环境维护与腐烂成本。纯标准库为 1；涉及第三方无头浏览器、易失效 API 为 8~10。
  • $\mathcal{O}_{\text{native}} \in [0, 10]$：与 Agent 原生内建工具的重叠度。无原生工具支持为 0；内建已有成熟 CLI/搜索工具为 8~10。

根据该公式推演：

  • docx-reference-builder：$\frac{1.0 \times 9}{1 + 2 + 0} = 3.0 \ge 1.0$（准予配置脚本）；
  • /verifier：$\frac{0.3 \times 2}{9 + 3 + 8} = 0.03 \ll 1.0$（严格禁止配置全局脚本）。

5.2 脚本引入“三不原则”

               ┌───────────────────────────────┐
               │    是否计划为 Skill 编写脚本?   │
               └──────────────┬────────────────┘
                              │
               ┌──────────────▼────────────────┐
               │ 规则 1: 是否硬编码了项目专用栈? │ ──是──> 【拒绝】下沉至项目级 .agents/
               └──────────────┬────────────────┘
                             否
               ┌──────────────▼────────────────┐
               │ 规则 2: 是否重复包装原生工具?   │ ──是──> 【拒绝】直接使用 run_command
               └──────────────┬────────────────┘
                             否
               ┌──────────────▼────────────────┐
               │ 规则 3: 是否试图替代高阶推理?   │ ──是──> 【拒绝】保留 Prompt 契约把控
               └──────────────┬────────────────┘
                             否
               ┌──────────────▼────────────────┐
               │    【准入】沉淀至 scripts/     │
               └───────────────────────────────┘
  1. 不写死项目专用技术栈
    全局 config/skills/ 严禁引入绑定特定语言包管理器或特定测试框架的运行脚本。任何项目私有的测试与验证逻辑，统一下沉至工作区目录下的 .agents/skills/。
  2. 不重复包装运行时原生工具
    严禁为了调用系统的 git、grep、curl 或 Agent 内置的 search_web 而单独编写 Python 包装层。原生接口能够直接完成的操作，不增加额外的抽象层次。
  3. 不替代高阶推理决策
    脚本的边界被严格限制在数据清洗、二进制读写、确定性拓扑计算。关于架构是否偏离、逻辑是否严密、假设是否需要清零等综合判定，统一保留在模型推理层与人工审查环节。

6. 责任与执行矩阵

为保证新架构在开发实践中得到稳定贯彻，各角色的执行职责与失效处理路径定义如下：

职责角色 覆盖技能范围 准入触发条件 标准执行动作 异常与失效处理路径
底层引擎组 Tier 1 (Deterministic) 涉及二进制、音频流或复杂 XML AST 解析 编写零副作用 CLI 脚本，输出结构化 JSON 或标准化文件 脚本执行失败时向 Agent 抛出精确错误码，阻断后续生成
工作流编排组 Tier 2 (Orchestration) 涉及多阶段编译、差异提取或格式转换 仅定义标准作业流程，通过 Shell 编排调用底层 Tier 1 脚本 依赖的底层工具缺失时，向用户抛出环境就绪度检查清单
元认知中枢组 Tier 3 (Meta-Cognitive) 跨项目通用研发、架构分析、排障与审计 仅维护 SKILL.md 契约；严禁引入特定语言测试脚本 遇到项目私有逻辑时，引导用户在 .agents/ 建立项目级覆盖
领域创作组 Tier 4 (Domain Writing) 行业洞察、技术复盘、学术论文撰写 仅通过自然语言定义论证递进、事实分离与结构约束 严禁配置任何脚本；若需事实支撑，调用 Tier 3 技能协同

7. 演进路径与后续行动

从平铺的全局工作流向模块化、渐进披露的 Skills 架构演进，标志着 Agent 辅助研发系统进入了精细化治理阶段：

  1. 历史资产的物理归档与基线收敛
    原 config/global_workflows/ 目录下的旧工作流已全量更名为 *.md.bak 并标记迁移状态，仅作为应急回滚缓冲区。所有系统架构设计方案与 ADR 统一收敛至 config/docs/，确保配置中心具备可追溯的工程基线。
  2. 项目级覆盖机制落地
    全局配置保持纯粹的跨语言、跨项目通用性。后续针对特定技术栈（如特定 Rust 微服务或 Web 前端项目）的构建检验需求，统一通过在工作区根目录构建 .agents/skills/ 实施精确注入。
  3. 深化确定性计算与推理契约的协同
    继续强化 Tier 1 引擎工具的计算吞吐能力，让代码执行代码，让推理负责推理。通过数学模型守住脚本边界，防止全局元认知技能发生职能漂移。

通过渐进式披露化解上下文拥塞，通过严格的准入模型阻断脚本盲目扩张。只有在灵活性与确定性之间划清工程界限，Agent 定制体系才能在跨语言、跨业务的研发实践中维持长期稳定的工程生产力。