⚡

扩展信号模式 extend-signal-schema

扩展信号模式技能是AFI核心框架中用于安全扩展和优化信号数据模式的工具。该技能专注于在量化金融交易系统中，为原始、丰富、分析和评分信号添加新字段或验证规则，确保变更的向后兼容性、遵循设计原则并保持验证确定性。适用于量化策略开发、数据工程、金融科技系统架构和AI智能体开发场景。

回测系统 0 次安装 0 次浏览 更新于 3/1/2026

name: extend-signal-schema description: > 安全地扩展或优化AFI信号模式及其紧密相关的验证器 在afi-core中，同时保持确定性，尊重PoI/PoInsight设计原则， 并遵守AFI Droid章程和AFI Core AGENTS.md中的边界。

技能：extend-signal-schema (afi-core)

目的

当您需要扩展或优化信号模式时使用此技能， 向原始、丰富、分析或评分信号模式中添加新字段或验证规则。

此技能确保变更：

  • 安全：尽可能向后兼容，并提供清晰的迁移路径
  • 受控：与AFI Droid章程、AFI Droid Playbook和afi-core/AGENTS.md保持一致
  • 正确：PoI/PoInsight保持为验证器级别的特性，而非信号字段
  • 经过测试：模式变更包含最低限度的测试覆盖

此技能主要由schema-validator-droid和任何未来处理信号模式和验证器的afi-core机器人使用。

前提条件

在进行任何更改之前，您必须：

  1. 阅读：

    • afi-core/AGENTS.md
    • AFI Droid章程
    • AFI Droid Playbook
    • schemas/目录中的目标模式文件

  2. 确认：

    • 请求的变更属于afi-core（信号语言/验证）， 而非afi-reactor（编排）或afi-token（经济模型）。
    • 变更不会将PoI/PoInsight作为信号字段引入。
    • 变更不需要编辑智能合约、Eliza配置或部署/基础设施仓库。

如果任何要求不明确或似乎违反了AGENTS.md或章程， 请停止并请求人工澄清，而不是试图自作聪明。

预期输入

调用者应以自然语言或结构化形式提供：

  • 目标生命周期阶段：原始、丰富、分析或评分
  • 字段名称：要添加或优化的字段
  • 类型/结构：例如，string、number、enum、object、array
  • 可选性：必需还是可选？如果可选，默认值是什么？
  • 描述：字段含义和用途的简要说明
  • 向后兼容性：任何迁移问题或破坏性变更？

如果缺少任何信息，请提出澄清问题，或生成一个带有TODO和保守默认值的最小化、清晰标记的存根。

分步说明

当调用此技能时，请遵循以下顺序：

1. 重述请求的变更

用您自己的话总结：

  • 正在修改哪个生命周期阶段（原始/丰富/分析/评分）
  • 正在添加或更改哪些字段
  • 每个字段的类型、可选性和目的
  • 任何向后兼容性或迁移问题

此摘要应简短精确，以便人工快速确认意图。

2. 定位模式文件

识别相关的模式文件，通常是：

  • schemas/universal_signal_schema.ts — 主信号模式（可能涵盖所有阶段）
  • schemas/pipeline_config_schema.ts — 管道配置模式
  • schemas/signal_finalization_request_schema.ts — 最终化请求模式
  • schemas/validator_metadata_schema.ts — 验证器元数据模式

或者，如果模式按阶段拆分：

  • schemas/raw_signal_schema.ts
  • schemas/enriched_signal_schema.ts
  • schemas/analyzed_signal_schema.ts
  • schemas/scored_signal_schema.ts

不要立即修改这些文件；只需了解当前结构。

3. 更新Zod模式

在目标模式文件中：

  1. 添加新字段并使用适当的Zod类型：

    • 对可选字段使用.optional()
    • 对具有默认值的字段使用.default(value)
    • 对枚举值使用.enum([...])
    • 对验证规则使用.min()、.max()、.regex()

  2. 添加清晰的注释以解释：

    • 字段的用途和用法
    • 字段在哪个生命周期阶段被填充
    • 任何约束或验证规则

  3. 保留现有字段：

    • 请勿静默重命名或删除现有字段
    • 如果要弃用某个字段，请明确标记并提供迁移指导

  4. 示例：

// schemas/universal_signal_schema.ts

export const SignalSchema = z.object({
  // ... 现有字段 ...

  // ✨ 新增：宏观状态分类（丰富阶段）
  // 值："risk_on"（看涨情绪）、"risk_off"（防御性）、"neutral"
  macro_regime: z.enum(["risk_on", "risk_off", "neutral"]).optional(),

  // ... 模式的其余部分 ...
});

4. 更新相关的类型导出

如果模式有相应的TypeScript类型：

  1. 导出推断出的类型：
export type Signal = z.infer<typeof SignalSchema>;
  1. 更新任何引用该模式的注册表接口：
    • 检查runtime/types.ts或schemas/index.ts
    • 确保导出的类型与更新的模式匹配

5. 更新验证器（如果需要）

如果新字段需要验证逻辑：

  1. 在validators/中定位相关的验证器：

    • validators/SignalScorer.ts — 信号评分逻辑
    • validators/index.ts — 验证器注册表

  2. 如果需要，添加验证逻辑：

    • 检查必需字段
    • 根据业务规则验证字段值
    • 记录任何非确定性行为

  3. 尽可能保持验证器的确定性：

    • 避免随机值、时间戳或外部API调用
    • 如果是非确定性的，请清晰记录

6. 添加或更新测试

在存在测试模式的地方：

  1. 为新字段添加单元测试：

    • 测试有效值
    • 测试无效值（应验证失败）
    • 测试可选与必需的行为

  2. 如果模式已更改，则更新现有测试：

    • 修复期望旧模式结构的测试
    • 为新字段添加新的测试用例

  3. 示例测试位置：

    • tests/ — Vitest单元测试
    • signal_schema_test/ — 模式特定的测试套件

如果尚不存在测试模式，请留下清晰标记的TODO并在摘要中说明。

7. 验证和构建

至少运行：

  • 在afi-core中运行npm run build

如果存在相关测试且可以安全运行：

  • npm test或npm run test:run（Vitest）

如果构建失败，请勿将技能标记为“成功”。相反，请停止，收集错误输出，并以最小化、清晰的评论说明。

硬性边界

使用此技能时，您绝不能：

  • 修改afi-reactor中的编排逻辑：

    • 请勿编辑DAG连接、管道执行或编排代码。
    • 模式变更属于afi-core；DAG连接属于afi-reactor。

  • 将PoI/PoInsight作为信号字段引入：

    • 请勿添加poi、poinsight、proof_of_intelligence或类似字段。
    • PoI/PoInsight是验证器级别的特性，而非信号级别的字段。
    • 如果请求要求这样做，请停止并上报。

  • 触及代币/经济模型：

    • 请勿修改afi-token中的智能合约、发行或代币经济学。

  • 修改Eliza代理或网关：

    • 请勿编辑Eliza代理配置、角色规范或运行时行为。
    • 请勿修改afi-gateway。

  • 触及基础设施/运维：

    • 请勿修改部署配置、Terraform、K8s或CI/CD。

  • 执行大规模重构：

    • 未经明确批准，请勿重构整个模式架构。
    • 没有迁移策略，请勿重命名或删除现有字段。

  • 破坏向后兼容性：

    • 没有弃用路径，请勿删除必需字段。
    • 未经人工批准，请勿以破坏性方式更改字段类型。

如果请求迫使您走向上述任何情况，请停止并上报。

输出 / 摘要格式

在成功的extend-signal-schema操作结束时，生成一个简短的摘要，包括：

  • 修改的生命周期阶段：原始、丰富、分析或评分
  • 添加/更改的字段：列出每个字段，包括：
    • 字段名称
    • 类型（字符串、数字、枚举、对象等）
    • 可选性（必需或可选）
    • 简要描述
  • 创建/修改的文件：
    • 模式文件
    • 验证器文件（如果有）
    • 类型导出文件
    • 测试文件
  • 构建/测试结果：通过或失败
  • 向后兼容性：任何破坏性变更或迁移说明
  • 待办事项或开放问题：任何需要人工决策的点

目标是让人类维护者在一分钟内阅读并准确理解更改内容和原因。

示例使用模式

使用此技能的场景

  • “向丰富信号添加一个可选的macro_regime字段，枚举值为risk_on、risk_off、neutral。”

  • “扩展评分模式以包含一个risk_breakdown对象，其中包含market_risk、liquidity_risk和execution_risk的子分数。”

  • “向分析信号添加一个derivative_underlier字符串字段，仅用于期权/期货信号。”

  • “向所有信号添加一个必需的content字段（已存在，但使其成为必需并制定迁移策略）。”

  • “优化action字段以包含新的枚举值：buy、sell、hold、close、reduce。”

不要使用此技能的场景

  • “将新模式连接到DAG管道中。” → 改为在afi-reactor中使用add-dag-node技能。

  • “将PoInsight作为评分信号的一个字段添加。” → 违反了PoI/PoInsight设计原则（上报给人工）。

  • “根据信号分数修改代币发行。” → 属于afi-token（上报给人工）。

  • “更新Eliza代理角色规范以使用新字段。” → 属于afi-gateway（上报给人工）。

  • “添加一个调用外部API的新验证器。” → 需要明确批准（上报给人工）。

迁移策略指导

当添加可能破坏向后兼容性的字段时：

对于可选字段（安全）

  • 使用.optional()添加字段
  • 无需迁移
  • 记录字段何时被填充

对于必需字段（破坏性）

  • 选项1：首先作为可选添加，然后在未来版本中设为必需
  • 选项2：使用.default(value)添加以提供向后兼容性
  • 选项3：提供明确的迁移脚本或指导

始终在摘要中记录迁移策略。

示例：添加可选字段

请求：“向丰富信号添加一个可选的macro_regime字段。”

摘要：

  • 修改的阶段：丰富（通过universal_signal_schema.ts）
  • 添加的字段：macro_regime
    • 类型：enum(["risk_on", "risk_off", "neutral"])
    • 可选性：可选
    • 描述：市场情绪的宏观状态分类
  • 修改的文件：
    • schemas/universal_signal_schema.ts（添加字段）
    • schemas/index.ts（重新导出的类型）
  • 构建/测试结果：✅ 通过
  • 向后兼容性：✅ 安全（可选字段）
  • 待办事项：无

示例：添加带默认值的必需字段

请求：“使content字段对所有信号都是必需的。”

摘要：

  • 修改的阶段：所有阶段（通过universal_signal_schema.ts）
  • 更改的字段：content
    • 类型：string（最小1，最大280）
    • 可选性：必需（原为可选）
    • 迁移：添加.default("")以提供向后兼容性
  • 修改的文件：
    • schemas/universal_signal_schema.ts（更改了可选性）
    • tests/signal_schema.test.ts（更新了测试）
  • 构建/测试结果：✅ 通过
  • 向后兼容性：⚠️ 通过默认值缓解了破坏性变更
  • 待办事项：考虑在迁移期后的v2.0中移除默认值

最后更新：2025-11-27 维护者：AFI核心团队 章程：afi-config/codex/governance/droids/AFI_DROID_CHARTER.v0.1.md