AGENTS.md — arknights-operator-skill

项目概览

明日方舟角色蒸馏工具，将游戏角色转化为结构化 AI Skill。采用 Knowledge + Persona 双轨分离架构，五层优先级 Persona 结构，支持资料导入、语境化分析、对话纠正和版本管理。

版本: 3.6.1（单一来源：pyproject.toml；变更见 CHANGELOG.md） 技术栈: Python 3 (标准库), Markdown, JSON 已验证角色: 特蕾西娅 (operators/te-lei-xi-ya/), W (operators/w/) 测试: python3 -m pytest tests/ -v (327 项通过 + 0 skipped，含多阵营泛化测试、v3.5.1/v3.6.0/v3.6.1 回归测试；类型检查 mypy tools/ 0 错误) 质量门禁: python3 -m ruff check tools/ tests/（0 违规） 工程配置: pyproject.toml (含 ruff、mypy、pytest 配置)

核心架构

• Knowledge (knowledge.md): 角色"知道什么" — 背景故事、阵营关系、事件时间线
• Persona (persona.md): 角色"如何存在" — 五层优先级性格结构 (Layer 0-4 + Layer 5 边界) + Correction 层
• context.json: 语境化数据中间层，统一标注场景/时期/对象
• phase_inferrer.py: 多层级时期自动推断引擎（消除手动映射依赖）

共享模块（v2.0 新增）

数据流

PRTS Wiki ──→ game_data_parser.py ──→ operator_data.json
                                          │
剧情页面 ──→ story_extractor.py ──→ story.json
                │                         │
                └── phase_inferrer.py ←───┘ (自动推断时期)
                                          │
                     context_annotator.py ←─┘──→ context.json (枢纽)
                          │      │
           phase_inferrer.py      │
           (自动推断默认时期)      │
                                  │
        ┌─────────────────┬───────┼────────────────┐
        ↓                 ↓       ↓                ↓
speech_act_analyzer  dialogue_fingerprint  relationship_graph  temporal_slicer
        │                 │       │                │
        └─────────────────┴───────┴────────────────┘
                                  │
                         persona_validator.py (多切片验证)
                                  │
                         knowledge.md + persona.md + SKILL.md

共享依赖关系：

constants.py  ←── 所有工具
prts_client.py  ←── game_data_parser, story_extractor, phase_inferrer
shared_utils.py  ←── 所有工具

Prompt 模板与工具调用关系

┌─────────────────────────────────────────────────────────────────────┐
│                        AI Agent 调用层                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  tools/_prompts/intake.md ──→ AI Agent 调用 game_data_parser.py            │
│                          + story_extractor.py                       │
│                          → 产出 operator_data.json + story.json     │
│                                                                     │
│  tools/_prompts/knowledge_analyzer.md ──→ AI Agent 分析原始数据            │
│                                      → 产出知识要点                 │
│                                                                     │
│  tools/_prompts/knowledge_builder.md ──→ AI Agent 生成 knowledge.md        │
│                                                                     │
│  tools/_prompts/persona_analyzer.md ──→ AI Agent 调用分析工具链:           │
│                                    speech_act_analyzer.py           │
│                                    dialogue_fingerprint.py          │
│                                    relationship_graph.py            │
│                                    temporal_slicer.py               │
│                                    persona_validator.py             │
│                                    → 产出分析画像                   │
│                                                                     │
│  tools/_prompts/persona_builder.md ──→ AI Agent 生成 persona.md            │
│                                  + skill_writer.py 写入文件         │
│                                                                     │
│  tools/_prompts/correction_handler.md ──→ AI Agent 处理用户纠正            │
│                                      → 更新 persona.md              │
│                                                                     │
│  tools/_prompts/merger.md ──→ AI Agent 合并多源数据                        │
│                         → 产出最终 SKILL.md                         │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

数据流向: Prompt 指导 AI Agent → Agent 调用工具 → 工具产出 JSON/MD → 下一轮 Prompt 消费产出

工具链

领域资产与产物（v3.6.0）

• 资产目录：tools/_data/*.json（随 wheel 分发）。解析顺序：ARKNIGHTS_DATA_DIR → 仓库根 data/（用户覆盖位）→ tools/_data → importlib.resources。 5 个 CLI（pipeline / game_data_parser / speech_act_analyzer / relationship_graph / canon_checker）启动即自检，缺失即以退出码 2 结束。
• 产物文件名：唯一来源 tools/artifacts.py（ARTIFACT / STEP_ARTIFACTS / ANALYZE_TOOLS）， 任何模块不得再写字面量文件名。--step analyze 产出 4 个分析 json，--step validate 产出 validation.json + persona_validation.json。
• 退出码：0 成功 / 1 运行期失败 / 2 用法或前置错误（统一经 tools/cli.py::finish()）。
• 写盘：JSON 用 atomic_write_json，文本用 atomic_write_text；读文本用 read_text_utf8 （UTF-8/BOM/GB18030 三档），读 JSON 用 load_json_safe / assets.load_json_or。 | semantic_matcher.py | 语义匹配原型（v3.5） | search / cluster / duplicates（探索性，未接入主管线） |

关键字段映射

• game_data_parser.py 输出语音行使用 label 字段（不是 title）
• context_annotator.py 已兼容 label 和 title，优先读取 label
• context.json 的 annotated_lines 每条包含: id, text, source, source_detail, context{phase, scene, interlocutor, situation_type}, speech_acts, emotion
• story_extractor.py 输出格式为 dict: {character, chapters[], dialogues[], phase_distribution, total_target_lines}

时期自动推断机制（phase_inferrer.py）

设计动机

旧版时期推断依赖三个手动映射表（OPERATOR_DEFAULT_PHASE、CHAPTER_PHASE_MAP、ACTIVITY_PHASE_MAP），每新增角色/章节需手动添加条目。phase_inferrer.py 通过多层级自动推断消除这一依赖。

推断优先级（从高到低）

自动推断结果示例

新增角色时的步骤（简化）

旧版需要 3 步手动配置，现在无需任何手动操作即可获得基本可用的结果：

1. 在 OPERATOR_DEFAULT_PHASE 添加映射 → phase_inferrer 自动从 PRTS 分类推断
2. 在 CHAPTER_PHASE_MAP 添加映射 → phase_inferrer 自动从活动元数据推断
3. 在 relationship_graph.py 的 NAME_ALIASES 添加角色别名（如有）— 仍需手动

仅在自动推断结果不满意时，可选地在 OPERATOR_DEFAULT_PHASE 中覆盖默认值。

推断报告

context_annotator.py 运行后会输出 inference_report，包含：

• unknown_pct: 未知时期占比
• confidence_distribution: 各置信度级别数量
• suggestions: 改进建议（如 unknown 占比 >50% 时提示使用 --interactive）

常见问题

语音行 source_detail 为空

• 原因: game_data_parser.py 输出 label 字段，旧版 context_annotator.py 读取 title 字段
• 修复: v3.1 已兼容两种字段名

persona_validator 切片样本不足

• 当某切片对话数 < 2 时跳过该切片
• 置信度: high(>=20) / medium(>=10) / low(>=3) / very_low(<3)

时期推断误标注

• 原因: context_annotator.py 的 PHASE_KEYWORDS 包含过于宽泛的关键词（如"和平"、"魔王"），导致语音行被错误归入 babel 时期
• 修复: v3.2 将"和平"替换为更精确的"和平协议"/"卡兹戴尔的和平"；"魔王"需要结合卡兹戴尔语境（通过 PHASE_PATTERNS 正则匹配）；新增 PHASE_PATTERNS 优先级高于 PHASE_KEYWORDS

关系轨迹时期排序错误

• 原因: relationship_graph.py 的 compute_relation_trajectories 使用字母序排列时期（"babel" < "early" < "resurrected"），导致"从 early 到 babel"的描述被错误写成"从 babel 到 resurrected"
• 修复: v3.2 使用预定义时序 PHASE_ORDER = ["early", "babel", "resurrected"]

话语行为标签重复定义

• 原因: act_labels 字典在 speech_act_analyzer.py 和 temporal_slicer.py 中各自定义，容易不同步
• 修复: v3.2 提取为 speech_act_analyzer.ACT_TYPE_LABELS，temporal_slicer.py 通过 import 引用

新角色时期全部为 unknown

• 旧版原因: 新角色的干员页面名不在 OPERATOR_DEFAULT_PHASE 中，且相关活动不在映射表中
• v3.4 修复: phase_inferrer.py 自动从 PRTS 分类标签和活动元数据推断，无需手动配置
• 兜底: 运行 python3 tools/context_annotator.py --interactive ... 可手动指定

否定上下文误提取关系

• 原因: relationship_graph.py 的否定词列表不全，如"没有背叛"被误提取为 betrayal 关系
• 修复: v3.3 补全 negation_markers，新增 "没有"、"不曾"、"未尝"、"并不"

Correction 规则覆盖 Layer 0

• 原因: 未明确 Correction 的作用范围，导致运行时纠正可能修改核心性格
• 修复: v3.3 在 persona.md 中明确标注 Correction 只能修改 Layer 1-4，不得覆盖 Layer 0

自动推断时期与预期不符

• 原因: PRTS 分类标签反映的是角色的"当前阵营归属"，而非"该语音行的时期"。例如 W 标注为"属于巴别塔的干员"，但其语音行可能属于早期（切尔诺伯格时期）
• 处理: 自动推断给出的是合理的默认值，如需精确控制可在 OPERATOR_DEFAULT_PHASE 中覆盖
• 建议: 使用 context_annotator.py --interactive 逐条确认低置信度推断

管线验证记录

特蕾西娅 (operators/te-lei-xi-ya/)

• game_data_parser: ✅ 从 PRTS 获取"魔王"页面，38 条语音行 + 9 份档案（v3.5.1 重新获取，修复了 v3.5.0 的空数据问题）
• story_extractor: ✅ BB-ST-3 提取 85 条对话（特蕾西娅 0 条，W 不在此章）
• context_annotator: ✅ 47 条标注数据（38 语音 + 9 档案），unknown 0%（v3.5.1 重新生成，修复了 v3.5.0 context.json 为空的问题）
• character 字段: ✅ "特蕾西娅"（v3.5.1 修正，v3.5.0 错误显示为 "魔王"）
• phase_inferrer: ✅ 自动推断"魔王"→ resurrected（PRTS分类: 属于罗德岛的干员）
• 下游工具: ✅ fingerprint / speech_act / temporal_slicer / persona_validator 全部重新生成并通过

W (operators/w/)

• game_data_parser: ✅ 从 PRTS 获取 W 数据，38 条语音行 + 8 份档案
• story_extractor: ✅ DM-ST-1 求生/NBT 提取 239 条对话（W 114 条），phase 全部为 babel（v3.5.1 修正 DM 映射从 early → babel）
• context_annotator: ✅ 160 条标注数据，phase_distribution: {early: 38, babel: 114}（v3.5.1 修正，v3.5.0 全部为 early）
• timeline id 一致性: ✅ timeline id 全部为英文 ['early','babel','integration']（v3.5.1 修正，v3.5.0 为中文导致 temporal_slicer 失效）
• phase_inferrer: ✅ 自动推断"W"→ babel（PRTS分类: 属于巴别塔的干员）
• 下游工具: ✅ fingerprint / speech_act / temporal_slicer 全部通过，temporal_slices.rule_count=5（v3.5.1 修正，v3.5.0 为 0）
• 注意: W 的 persona.md 已创建（v3.4 后），persona_validator 可正常运行

环境变量

编码规范

• Python 3 标准库，无第三方依赖（可选: pypinyin）
• 文件编码: UTF-8
• JSON 输出: ensure_ascii=False, indent=2