{
  "title": "企业 Agent 工程知识图谱",
  "evidenceAsOf": "2026-10-15",
  "relationLabels": {
    "requires": "依赖",
    "feeds": "供给",
    "controls": "约束",
    "verifies": "验证",
    "implements": "实现",
    "alternative-to": "可替代",
    "complements": "互补"
  },
  "relationNote": "parentId为导航层级；links为有方向的工程分析关系，不代表厂商合作。backboneRelations为总览主干映射，可能与详细links重合。",
  "backboneRelations": [
    {
      "source": "storage",
      "target": "knowledge",
      "label": "保存原件与元数据",
      "type": "feeds",
      "reason": "存储提供知识原件、版本和权威元数据。"
    },
    {
      "source": "knowledge",
      "target": "retrieval",
      "label": "供给版本证据",
      "type": "feeds",
      "reason": "经过治理的知识版本进入检索管线。"
    },
    {
      "source": "retrieval",
      "target": "memory",
      "label": "支持记忆召回",
      "type": "complements",
      "reason": "检索机制可复用于受控记忆召回，作用域仍由记忆策略决定。"
    },
    {
      "source": "foundations",
      "target": "models",
      "label": "限定任务与输入",
      "type": "controls",
      "reason": "任务合同限定模型需要的能力、上下文和预算。"
    },
    {
      "source": "models",
      "target": "runtime",
      "label": "提供推理",
      "type": "feeds",
      "reason": "模型适配层向执行循环提供生成与工具请求。"
    },
    {
      "source": "runtime",
      "target": "performance",
      "label": "形成关键路径",
      "type": "feeds",
      "reason": "执行轨迹为延迟、缓存和成本优化提供测量依据。"
    },
    {
      "source": "security",
      "target": "operations",
      "label": "约束数据与执行",
      "type": "controls",
      "reason": "运营与观测必须遵守身份、数据和动作政策。"
    },
    {
      "source": "operations",
      "target": "evaluation",
      "label": "供给轨迹与结果",
      "type": "feeds",
      "reason": "生产轨迹与故障样本进入受控评测。"
    },
    {
      "source": "evaluation",
      "target": "learning",
      "label": "定位改进候选",
      "type": "feeds",
      "reason": "分层评测识别需要改进的检索、上下文、技能或权重。"
    },
    {
      "source": "retrieval",
      "target": "runtime",
      "label": "证据",
      "type": "feeds",
      "reason": "检索为执行提供有权限、可定位的证据。"
    },
    {
      "source": "runtime",
      "target": "evaluation",
      "label": "产物 / 轨迹",
      "type": "feeds",
      "reason": "执行产物与可见轨迹构成任务验收输入。"
    },
    {
      "source": "learning",
      "target": "models",
      "label": "通过评测后发布候选",
      "type": "feeds",
      "reason": "模型、提示和上下文候选通过门禁后进入新发布。"
    }
  ],
  "nodes": [
    {
      "id": "domain-finance-workflow",
      "title": "金融投研Agent端到端流程",
      "aliases": [
        "金融投研",
        "投资研究",
        "as_of"
      ],
      "kind": "case",
      "parentId": "domains-finance",
      "order": 1,
      "summary": "从主体和截止日出发，完成取证、口径处理、程序计算、反证、备忘录与版本化交付。",
      "question": "金融研究从身份和时点到报告交付，应怎样组织完整流程？",
      "body": "## 先把投研任务变成合同\n金融Agent首先确认分析目的、legal entity与证券身份、研究截止时间、允许来源、交付物和操作边界。公司名称、ticker、ADR与普通股不一定一一对应，标的识别错误会让后续所有数字看似合理却属于另一实体。创建business task时保存主体标识、范围、可用数据资格与验收；研究、风险分析、组合决策和交易执行分别建模，不能由“帮我分析”自动推导下单权限。\n\n## 取证保留期间和公开可得时间\n原始披露、结构化财务与有许可研究材料各自保留来源版本。每条事实带报告期、币种、单位、口径、发布日期、available_at及重述关系；季度、累计、TTM、合并和分部数据不能直接混算。SEC submissions与XBRL API是公开起点，但自定义taxonomy、财政年度与单位仍需解释。无法取得的指标保持缺失，不用邻近指标推成正式事实，更不能默认填零。\n\n## 让程序负责可复算部分\n由受控计算工具处理增长率、利润率、现金流、估值和敏感性，返回公式、输入引用、单位与精度。Agent负责比较经营驱动、管理层说法、替代解释与反证，而不是依靠自由文本心算。把GAAP与non-GAAP、自由现金流定义、非经常项和受限现金显式列出；预测和事实使用不同字段，记录关键假设与影响方向。\n\n## 验证后再交付可审阅产物\n交付报告、计算表、假设、来源和验证报告。关键数字必须能回到原始片段并复算，引用支持对应主张，cutoff之后才公开的资料不得混入。严重错误设硬阻断，证据不足可交付部分结论和未决清单。需要专家时给具体差异、证据与风险，而不是笼统请人“看一下”。任务完成不要求强行给买卖结论。\n\n## 后续更新是新任务\n新财报或重大事件触发新的task，旧报告保留原版本和当时证据，并可标过时。memory保存分析偏好和方法候选，不把“看好这家公司”固化为永久事实。财报重述、同名公司、汇率变化、融资承诺未到账、现金受限和预算不足，分别标出受影响的结论；不要让一个字段缺失造成全报告无解释地失败。\n\n## 效果边界\n带来源报告的准确性、分析过程质量、前瞻预测校准和实际投资收益是不同验证层。用较晚模型回看历史事件还可能从参数中泄漏未来结果；回测需另控制时序、幸存者偏差、成本、滑点和多重检验。此流程是工程蓝图，不承诺收益，也不把一次漂亮回测当持续能力。",
      "blueprint": {
        "inputs": [
          "公司与证券身份",
          "分析目的与as_of",
          "授权披露与研究材料"
        ],
        "steps": [
          "核主体和数据资格",
          "抽取期间、单位与版本",
          "程序计算并收集反证",
          "独立验证后交付"
        ],
        "outputs": [
          "研究报告与计算表",
          "假设、引用与未决项"
        ]
      },
      "citations": [
        {
          "url": "https://www.sec.gov/search-filings/edgar-application-programming-interfaces",
          "label": "SEC：EDGAR APIs",
          "kind": "official-doc",
          "note": "原始资料支持方法背景；本页流程与验收为工程建议。"
        }
      ],
      "links": [
        {
          "target": "domain-finance-verification",
          "type": "requires",
          "reason": "数字、口径、时点和证据决定验收。"
        }
      ],
      "en": "Financial Research Workflow"
    },
    {
      "id": "domains-finance",
      "title": "金融投研",
      "aliases": [
        "domains-finance"
      ],
      "kind": "branch",
      "parentId": "domains",
      "order": 1,
      "summary": "实体、时点、口径、可复算分析与预测边界。",
      "question": "这一领域如何定义任务、证据、异常和可验证结果？",
      "body": "金融投研应用从法律实体与证券身份、分析用途和截至时点开始。公告期末不等于披露可得日，市值不等于企业价值，复权价格与现金股利也可能改变收益口径；这些差异必须进入结构化事实和计算合同。\n\n先阅读投研流程，理解取证、抽取、计算、反证和报告交付，再阅读验证页，检查单位、期间、汇率、公司行动与point-in-time切分。研究质量、预测能力和真实投资结果分别评估；没有前瞻数据与交易成本证据，不能把历史回测或报告评分写成投资效果保证。",
      "blueprint": {
        "inputs": [
          "领域任务与权限"
        ],
        "steps": [
          "确认范围",
          "收集证据",
          "验证结果"
        ],
        "outputs": [
          "产物与未决项"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：按Agent任务设计评测",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "eval-case-contract",
      "title": "评测任务合同与成功条件",
      "aliases": [
        "EvalCase",
        "成功条件",
        "任务合同"
      ],
      "kind": "concept",
      "parentId": "evaluation-data",
      "order": 1,
      "summary": "将业务目标转成可执行、可解释的成功条件，并区分结果、动作与轨迹评分。",
      "question": "开放任务如何定义成功、硬约束和无法判定？",
      "body": "## 先规定什么叫成功\n企业任务的评测应从业务合同开始，而非从一个通用分数开始。合同要写清目标、输入、授权主体、知识截止时间、允许动作、必需产物和禁止结果。例如财报比较不能只要求“生成一份报告”，还应要求每个指标有期间、单位、来源和可复算公式。允许答案有多种表达，关键约束必须保持一致。若两位领域专家对同一结果是否通过持续分歧，先修合同，不宜直接增加模型judge。\n\n## 把合同落成可执行对象\n一个EvalCase保存任务指令、初始业务状态、对话前缀、数据快照、权限、期望终态、允许变化、禁止副作用、grader版本和切片标签。把目标拆成结果检查、动作检查和轨迹检查：结果看交付是否可用，动作看授权与外部效果，轨迹只检查必要顺序及成本。不要要求Agent复刻唯一参考路线，否则更短、更安全的合法路径也可能被判错。\n\n## 硬门槛与语义质量分开\n关键金额错误、越权读取、伪造引证、未授权发送应设硬门槛，不能被清晰文风抵消。覆盖程度、解释质量、论证完整性可以用分项rubric。保留证据不足、无法判定、任务未完成和评测器故障，不能全部折算为同一失败，更不能把unknown当作通过。每项判分应指出具体证据，而不是仅给一个总分。\n\n## 同时维护能力集和回归集\n能力集包含目前尚难完成的任务，用于发现模型或harness进步带来的新机会；回归集保护已经承诺的行为。能力成熟后可晋升为回归项，但最终选型还需未反复暴露的持出集。本页给出的是工程合同建议；官方评测文章提供方法背景，不代表任意领域可沿用同一阈值。\n\n## 用例合同示例\n以更新投研报告为例，允许读取已授权公告并改写草稿，成功条件是交付指定文件、结论与证据一致且数字可复算；不允许自动发送给客户。公告缺页时，应列缺口并暂停相关结论，而不是用常识补数。合同还要说明可接受的报告结构、必须覆盖的反证、截至时点与验收主体。这样才能接受多种正确写法，同时拦住越权完成。",
      "blueprint": {
        "inputs": [
          "业务任务与风险等级",
          "材料与授权初态",
          "允许变化与交付范围"
        ],
        "steps": [
          "定义终态和禁止副作用",
          "列证据、预算与升级条件",
          "指定pass/fail/unknown",
          "冻结合同与评分版本"
        ],
        "outputs": [
          "版本化EvalCase",
          "成功条件和硬阻断"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc",
          "note": "2026-01-09；官方方法背景，具体合同与阈值须按业务验证。"
        }
      ],
      "links": [],
      "en": "Task Contract"
    },
    {
      "id": "evaluation-data",
      "title": "数据与合同",
      "aliases": [],
      "kind": "branch",
      "parentId": "evaluation",
      "order": 1,
      "summary": "定义任务、样本与可重放条件。",
      "question": "如何把这项机制变成可执行、可核查的工程合同？",
      "body": "可靠评测先有可执行合同，再有数据和试验。这里把成功条件、样本构建与Trial重放放在同一条阅读路径：先规定业务终态和禁止结果，再挑选代表性及边界任务，最后固定初态、候选版本和评分环境。\n\n数据不只是一列问题与标准答案，还包括可见证据、授权、工具与memory预置、允许的不同正确路径和无法判定条件。真实来源与合成样本分别标记，开发集用于迭代，隐藏集用于独立资格判断。若初态或工具版本漂移，先识别实验条件变化，再讨论模型能力升降。",
      "blueprint": {
        "inputs": [
          "业务目标与约束"
        ],
        "steps": [
          "明确适用范围",
          "选择可执行检查",
          "保留结果与证据"
        ],
        "outputs": [
          "可审阅的设计合同"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc",
          "note": "2026-01-09；官方方法背景，具体合同与阈值须按业务验证。"
        }
      ],
      "links": []
    },
    {
      "id": "learning-method-selection",
      "title": "先定位瓶颈再选学习方式",
      "aliases": [
        "学习路线",
        "根因",
        "五种学习"
      ],
      "kind": "concept",
      "parentId": "learning-methods",
      "order": 1,
      "summary": "区分运行内适应、memory、skill、harness改进和权重训练，按根因选择最小有效改变。",
      "question": "何时改工具或记忆，何时才值得改变模型权重？",
      "body": "## 五种改变分别解决什么\n运行内适应利用当前context调整计划，结束后未必保留；memory保存带scope的事实与偏好；skill沉淀可复用方法；harness优化工具、检索、控制和验证；权重训练改变模型参数。前四种可以提高系统表现而底层模型完全不变。不要用“自我学习”把这些通道混在一起，分别记录变更对象、验证方式、删除责任与回滚范围。\n\n## 先从失败证据定位瓶颈\n找不到资料先检查连接器、解析、召回、rerank与ACL；算错先用程序；参数错先修工具描述和错误反馈；跨session丢状态先修持久日志和memory；重复写入先修幂等。只有正确证据已经可用、接口和约束合理，模型仍稳定出现行为缺口，才把微调作为优先候选。强模型对照也能帮助判断是能力上限还是环境问题。\n\n## 用最小改变形成可比较实验\n固定任务、数据、权限和预算，比较原方案、prompt或工具改进、不同模型以及训练候选。记录目标能力、预期收益和不应退化的切片；用开发集迭代，用持出任务确认泛化。不能以训练loss更低、记忆更多或模型自称更会做事代替端到端证据。\n\n## 晋升看增量收益\n将每成功任务成本、人工修订、严重错误、尾延迟及维护开销一起比较。训练和运营需要持续投入，历史投入不构成强行上线的理由。允许系统自动提方法或配置diff，但把权限、隐藏grader和正式发布指针留在受信控制层。学习的目标是可迁移能力，而非背住某家公司的答案或某位学生的一段对话。",
      "blueprint": {
        "inputs": [
          "失败trace和业务目标",
          "模型数据工具现状",
          "方案及成本预算"
        ],
        "steps": [
          "分知识控制能力根因",
          "选择五类学习通道",
          "以最小改变做基线对照",
          "用持出成本判断增量"
        ],
        "outputs": [
          "学习路线和实验假设",
          "变更对象及晋升条件"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent评测方法",
          "kind": "official-doc",
          "note": "学习收益需在独立业务任务验证。"
        }
      ],
      "links": [
        {
          "target": "eval-trajectory",
          "type": "requires",
          "reason": "学习方法由失败根因决定。"
        }
      ],
      "en": "Learning Method Selection"
    },
    {
      "id": "learning-methods",
      "title": "学习方法",
      "aliases": [
        "learning-methods"
      ],
      "kind": "branch",
      "parentId": "learning",
      "order": 1,
      "summary": "方法选择与外部知识、记忆和权重的边界。",
      "question": "如何积累可迁移能力并保留可验证的发布边界？",
      "body": "选择学习路线之前，先判断缺口来自知识、工具、控制还是模型行为。找不到文件应查连接器和召回，算错可先用程序，跨会话丢状态先查持久化，只有正确证据与合理接口均已具备时，才把权重训练作为优先候选。\n\n本分支从五种学习通道及其边界入手，比较最小改动、强模型对照和训练方案。读完后应能写出目标能力、变更对象、收益假设与不能退化的切片，再进入数据和具体训练方法。无论选择哪条路线，都通过独立任务和维护成本判断收益，而不是以新术语或训练loss代替产品价值。",
      "blueprint": {
        "inputs": [
          "目标能力与合格数据"
        ],
        "steps": [
          "定位缺口",
          "提出并验证候选",
          "受控发布"
        ],
        "outputs": [
          "版本化能力与评测证据"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent评测方法",
          "kind": "official-doc",
          "note": "学习收益需在独立业务任务验证。"
        }
      ],
      "links": []
    },
    {
      "id": "talk-production-harness",
      "title": "实践讲座：生产Harness可靠性",
      "aliases": [
        "Vinoth Govindarajan",
        "生产可靠性"
      ],
      "kind": "reference",
      "parentId": "talks-reliability",
      "order": 1,
      "summary": "Vinoth Govindarajan讨论持久状态、并发写、超时、审批和用户侧交付证明。",
      "question": "生产可靠性讲座如何帮助设计状态、审批和交付证明？",
      "body": "## 讲者与资料范围\nVinoth Govindarajan在AI Engineer World's Fair 2026的《Your Agent Didn’t Fail. Your Harness Did.》讨论生产系统可靠性。资料依据为原发布方完整带时间戳逐字稿；文字分析不等于连续观看视频，也不等于复现案例。页面可核会议年与18:26时长，确切上传日未作为事实使用。讲者以OpenClaw公开问题说明边界，并非以其维护者身份作产品承诺。\n\n## 观点：回答结束后证据仍要存在\n讲座围绕状态缺口、并发覆盖、悬空工具调用、审批漂移和缺少用户侧交付证明展开。2:39提出模型建议动作、harness提交、receipt证明；8:11讨论两次局部正确写入仍会丢更新；13:00区分组件成功与用户真正看到结果。这些案例说明流畅回答和正常日志，不足以证明跨轮运行可靠。\n\n## 工程含义：为每类事实指定权威\n企业实现应明确会话属于日志、工单状态属于工单系统、偏好属于memory，给每个事实一个可重放依据。并行检索可以保留，但共享可变资源需要有序提交或版本检查；写操作超时进入结果未知，而不是直接重试。恢复指令还要有独立于堵塞队列的通道，避免取消和修复也被卡住。\n\n## 将讲座转成验收\n选择一条真实业务路径，逐项检查触发身份、继承状态、授权、执行和幸存证据。验证报告核用户关心的终态，并记录未确认，而非仅抄工具的成功文本。SDK提供接口不代表应用自动满足全部条件；具体系统仍需kill/restart、重复回调、并发写和交付失败测试。上述验收是对观点的工程推导，不是讲者报告的企业实测。",
      "blueprint": {
        "inputs": [
          "生产业务路径",
          "会话任务及写入trace",
          "用户侧交付合同"
        ],
        "steps": [
          "识别事实的权威来源",
          "串行提交共享变更",
          "设计未知结果和恢复",
          "用receipt核真实交付"
        ],
        "outputs": [
          "状态审批并发验收表",
          "重启超时及交付用例"
        ]
      },
      "citations": [
        {
          "url": "https://ai.engineer/talks/BInpv7lGp1o-your-agent-didnt-fail-your-harness-did",
          "label": "原发布方完整逐字稿",
          "kind": "talk",
          "note": "文稿分析不代表连续观看、演示复现或现行产品资格。",
          "locator": "2:39 状态提交；8:11 并发写；13:00 交付边界"
        },
        {
          "url": "https://www.youtube.com/watch?v=BInpv7lGp1o",
          "label": "原始视频",
          "kind": "talk",
          "note": "文稿分析不代表连续观看、演示复现或现行产品资格。"
        }
      ],
      "links": [
        {
          "target": "eval-deterministic-verifier",
          "type": "complements",
          "reason": "用户侧回执展示验证边界。"
        },
        {
          "target": "agent-harness",
          "type": "complements",
          "reason": "将讲座中的状态和receipt机制转成harness设计问题。"
        }
      ],
      "en": "Production Harness Talk"
    },
    {
      "id": "talks-reliability",
      "title": "系统与可靠性",
      "aliases": [
        "talks-reliability"
      ],
      "kind": "branch",
      "parentId": "talks",
      "order": 1,
      "summary": "持久状态、执行环境和长任务的工程观点。",
      "question": "这场讲座提出什么机制，哪些结论可迁移到企业设计？",
      "body": "长任务可靠性不仅取决于模型推理，也取决于状态、并发、审批、执行环境和用户侧证据。本组从生产harness故障进入，再看接口、loop、沙箱与持久历史的演进，帮助划分哪一层负责保存事实和提交动作。\n\n阅读时把讲者案例转成具体问题：重启能恢复什么，工具超时后真实结果在哪里，审批是否仍对应原参数，外部memory整理能否追溯与撤销。讲座给出机制和经验，实际系统仍需并发写、取消、撤权、长任务与交付失败的独立验证。历史性能与托管产品能力保留其当时证据边界。",
      "blueprint": {
        "inputs": [
          "原始讲座文稿",
          "待设计的企业任务"
        ],
        "steps": [
          "区分讲者主张与证据",
          "抽取可迁移机制",
          "形成可执行验证"
        ],
        "outputs": [
          "设计问题与验收项",
          "证据及适用边界"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent评测方法背景",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "domain-finance-verification",
      "title": "金融数据、计算与时序验证",
      "aliases": [
        "point-in-time",
        "复权",
        "财务口径"
      ],
      "kind": "case",
      "parentId": "domains-finance",
      "order": 2,
      "summary": "核对期间、币种、单位、corporate actions和可获得时间，并区分报告质量与投资预测效果。",
      "question": "怎样验证金融数字、复权口径和决策时点可得信息？",
      "body": "## 先验证数字的身份\n数值检查必须同时核实体、指标、期间、币种、单位、会计口径和来源版本。同比与环比不同，百分点与百分比不同；每股数据和总额、季度与累计、财年与自然年都可能合法却不可直接比较。验证器应读取这些结构化字段，而不是只对最终浮点数设置容差。实体解析、ticker变更、ADR比例和分部口径也进入检查。\n\n## 计算建立可重放链\n每个输出指标保存公式、输入fact_id、转换规则、汇率日期、舍入和异常处理。对现金跑道明确现金是否可动用、burn用什么窗口、是否季节性，融资承诺不能当已到账。对收益序列明确拆股、分红和其他corporate actions处理，以及价格采用哪种复权定义。先做确定性复算，再让语义judge评价解释；漂亮文风不能投票消除算术错误。\n\n## Point-in-time不只是一列日期\n保留publication_time与available_at以及原始和重述链。较晚发布的重述值不能回填给较早决策；未来指数成分、并购退市后漏样本和幸存者偏差会抬高回测。时间前滚之外，可按公司和行业持出，检验是否只是熟悉某些实体。资料截止日约束可见输入，却无法保证晚训练的模型参数没有见过随后结果。\n\n## 从报告准确走向预测检验\n报告层看数字、引证与事实和观点分离；决策辅助层看假设、反证、风险和专家修订；预测层看冻结版本后的前瞻校准和适当基准。收益型实验另计成本、滑点、延迟、风险约束与多重比较，不与检索或工具benchmark混合宣传。FinQA提供数值推理任务与程序化依据，适合补算术评测，不能充当投资预测或收益证明。\n\n## 错误与缺失要有不同处理\n单位错、主体错、未经许可数据和伪造来源应阻断关键结论；资料缺失、口径冲突或无法核可得时间则保留unknown并解释影响。基准答案本身也可能有错误，专家应能追到原文裁决。分开统计硬错误、合理拒绝、数据服务故障、解释质量与人工耗时，不用一个平均分盖过高损失失误。\n\n## 可交付的验证报告\n报告绑定产物hash、task合同、as_of快照、计算和grader版本，列检查结果、证据定位、未决项与责任人。数据更新或报告修改后重新验证。历史材料与API文档能支撑机制设计，实际数据许可、市场覆盖和服务时延仍要在选定供应商与代表负载下测试。",
      "blueprint": {
        "inputs": [
          "结构化facts与原文",
          "公式、汇率与复权规则",
          "决策时点快照"
        ],
        "steps": [
          "核实体和口径",
          "复算并追溯输入",
          "检查可获得时间与泄漏",
          "分层评估报告与预测"
        ],
        "outputs": [
          "数值与时序验证报告",
          "错误等级与影响范围"
        ]
      },
      "citations": [
        {
          "url": "https://www.sec.gov/search-filings/edgar-application-programming-interfaces",
          "label": "SEC：期间和单位",
          "kind": "official-doc",
          "note": "原始资料支持方法背景；本页流程与验收为工程建议。"
        },
        {
          "url": "https://arxiv.org/abs/2109.00122",
          "label": "FinQA：金融数值推理",
          "kind": "paper",
          "note": "原始资料支持方法背景；本页流程与验收为工程建议。"
        }
      ],
      "links": [
        {
          "target": "eval-holdout-contamination",
          "type": "requires",
          "reason": "前瞻性声明要处理时间与参数泄漏。"
        },
        {
          "target": "eval-deterministic-verifier",
          "type": "requires",
          "reason": "金额、比率和收益应复算。"
        }
      ],
      "en": "Financial Verification"
    },
    {
      "id": "domains-education",
      "title": "教育辅导",
      "aliases": [
        "domains-education"
      ],
      "kind": "branch",
      "parentId": "domains",
      "order": 2,
      "summary": "作答证据、分层提示、迁移和延迟保持。",
      "question": "这一领域如何定义任务、证据、异常和可验证结果？",
      "body": "教育Agent应围绕学生的可观察作答组织互动，而非只展示标准答案。任务包含课程目标、当前证据、提示层级、下一步观察和教师升级；记忆保存可纠正的概念级观察，避免把暂时错误变成永久标签。\n\n先看教学流程，理解诊断、递进提示和独立验证；再看学习效果页，区分系统正确性、当场答对、迁移和延迟保持。题库、学生与班级的关联影响数据划分和实验单位。教师辅助研究不自动证明全自动教学有效，满意度和使用时长也不能代替学习增益。",
      "blueprint": {
        "inputs": [
          "领域任务与权限"
        ],
        "steps": [
          "确认范围",
          "收集证据",
          "验证结果"
        ],
        "outputs": [
          "产物与未决项"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：按Agent任务设计评测",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "eval-dataset-curation",
      "title": "评测集构建与切片",
      "aliases": [
        "评测集",
        "金标",
        "风险切片"
      ],
      "kind": "concept",
      "parentId": "evaluation-data",
      "order": 2,
      "summary": "从真实任务、失败与专家标注建立覆盖正常、边界、拒绝和异常情形的用例集。",
      "question": "怎样让评测集覆盖真实需求和低频严重错误？",
      "body": "## 数据集代表哪一种真实工作\n先列产品承诺的任务家族，再从有使用资格的真实任务、人工验收记录和失败中抽样。仅收集“难题”会扭曲整体成功率，仅收集顺利完成的任务又会漏掉异常。用任务频率、出错损失、语言、数据格式、角色权限和完成时长建立切片；保留原始分布评估集，同时维护面向风险的压力集，分别报告结果。\n\n## 一条用例需要足够的事实\n用例应保存用户当时的目标、可见资料、业务初态、允许工具、截止时间和可接受结果。领域专家写金标及理由，标注哪些字段必须正确、哪些措辞可变化、哪些问题本身没有答案。遇到来源冲突或任务含糊，应把追问和保留意见设为合法行为；不要偷偷补入实际执行时不可见的信息，使参考答案比任务本身知道得更多。\n\n## 合成数据补边界，不包办真实性\n合成样本适合构造缺失表头、过期批准、同名实体、工具超时、矛盾条款等低频情形。生成器和被测模型可能共享偏差，因此人工抽审样本可解性，去掉模板近重复，并用真实任务检查分布覆盖。一个公开benchmark可以筛选候选，但它的题型、权限和成本合同通常不同于企业业务。\n\n## 从小样本走向稳定维护\n早期可先用每个关键场景几十条真实任务发现大问题，同时明确这不足以证明极低风险。为每条样本记录来源、加入原因、owner、标签、版本和退役条件。新反馈进入候选池，由专家筛选后成为正式用例；不能把点赞直接写成正确、差评直接写成错误。每次扩集同时检查类别比例和难度变化，防止分数变动只是尺子换了。\n\n## 留下进入与退出的理由\n每个样本保存入选原因、来源日期、任务家族、风险标签、标注者及版本。重复投诉不能简单重复计权，同一底层故障可能在十个会话出现；也不能因为修复后已通过就从回归集中删掉。新增业务先补代表性任务，暂不具有可信标准答案的样本进入待标注池。模型生成的边界题由专家确认其真实可发生性和答案条件，避免测试集只剩人造难题。",
      "blueprint": {
        "inputs": [
          "真实任务及失败trace",
          "风险和语言分布",
          "合格合成边界样本"
        ],
        "steps": [
          "按任务家族去重分组",
          "补无答案、冲突及罕见风险",
          "专家标注允许答案范围",
          "冻结切片、权重与持出集"
        ],
        "outputs": [
          "数据manifest与金标",
          "开发集、回归集和隐藏test"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc",
          "note": "2026-01-09；官方方法背景，具体合同与阈值须按业务验证。"
        }
      ],
      "links": [
        {
          "target": "eval-case-contract",
          "type": "requires",
          "reason": "先定义目标与允许变化，才能挑选并标注用例。"
        }
      ],
      "en": "Dataset Curation"
    },
    {
      "id": "evaluation-targets",
      "title": "评测对象",
      "aliases": [],
      "kind": "branch",
      "parentId": "evaluation",
      "order": 2,
      "summary": "分别检验结果、工具、轨迹、检索、记忆与权限。",
      "question": "如何把这项机制变成可执行、可核查的工程合同？",
      "body": "Agent的失败可能发生在不同层：回答语义正确却没交付、工具参数合法却作用于错误对象、检索命中却引用不支持结论、记住事实却跨用户污染。这里按被测对象拆页，防止一个平均分掩盖不同故障。\n\n先阅读四层保真度，理解工具直接测试、自然语言循环、完整harness和产品交付的差别；再分别检查终态、动作、轨迹、RAG、memory和安全。每项结果连接具体证据与根因，并在同一任务合同下汇总。真实生产资格需要覆盖权限、外部状态和用户边界，模拟环境的分数应保留其适用限制。",
      "blueprint": {
        "inputs": [
          "业务目标与约束"
        ],
        "steps": [
          "明确适用范围",
          "选择可执行检查",
          "保留结果与证据"
        ],
        "outputs": [
          "可审阅的设计合同"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc",
          "note": "2026-01-09；官方方法背景，具体合同与阈值须按业务验证。"
        }
      ],
      "links": []
    },
    {
      "id": "learning-data",
      "title": "训练资产与发布",
      "aliases": [
        "learning-data"
      ],
      "kind": "branch",
      "parentId": "learning",
      "order": 2,
      "summary": "连接样本资格、监督目标、实验manifest和可回退的训练产物。",
      "question": "如何积累可迁移能力并保留可验证的发布边界？",
      "body": "训练资产与发布共同决定实验能否被理解、复现和撤销。入口是样本的来源、用途授权、去标识、纠正轨迹与监督目标；出口是基座、adapter、模板、量化、serving和数据manifest组成的候选发布。\n\n先阅读训练数据合同，确认哪些内容能用、哪些token应学习、如何分组去重及响应撤权；再阅读训练发布，把学习曲线、基线、持出结果和部署变换连接起来。数据资格与推理访问资格分别管理，训练中的好结果不能越过完整harness和受控灰度。高变化事实通常更适合保留在可更新且可追溯的外部知识层。",
      "blueprint": {
        "inputs": [
          "目标能力与合格数据"
        ],
        "steps": [
          "定位缺口",
          "提出并验证候选",
          "受控发布"
        ],
        "outputs": [
          "版本化能力与评测证据"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent评测方法",
          "kind": "official-doc",
          "note": "学习收益需在独立业务任务验证。"
        }
      ],
      "links": []
    },
    {
      "id": "learning-data-contract",
      "title": "训练数据资格与轨迹治理",
      "aliases": [
        "训练数据",
        "loss masking",
        "授权"
      ],
      "kind": "concept",
      "parentId": "learning-data",
      "order": 2,
      "summary": "保存数据用途许可、可见证据、版本、专家修订与分组；失败轨迹不直接成为SFT正向目标。",
      "question": "哪些轨迹有资格训练，哪些token应该作为监督目标？",
      "body": "## 可读不等于可训练\n每条训练样本保存来源、授权主体、用途许可、保留期限、脱敏状态、任务家族、输入可见证据、工具版本、目标输出和专家修订。企业拥有访问材料的账号，并不自动拥有模型训练或教师蒸馏权；知识接入、评测使用、训练使用和对外发布应分别判断。数据资格随撤权和合同变化更新。\n\n## 监督目标必须明确\n工具轨迹匹配实际chat template、tokenizer、工具schema以及call/result格式。明确loss覆盖哪些角色和token，通常不要将用户私有输入、工具事实或错误动作直接当作模型要模仿的目标。原失败轨迹可用于诊断或偏好负例；SFT正向目标使用经纠正的响应和恢复行为，错误步骤按目标屏蔽或明确标注。\n\n## 划分依据真实关联\n按公司、文档、合同matter、课程、学生或题型家族分组并去近重复；金融再按公开可得时间划分。相邻段落与同一报告改写不能横跨train和test，教师合成的近似题也可能污染。锁定test不反复回馈给优化器，并保留后来新建的fresh audit。历史金融任务还需警惕基础模型参数已知道未来结果。\n\n## 数据集是可追溯资产\n保留正确拒绝、无答案、冲突、工具失败和恢复的合格样本，避免只教完美短路径。数据manifest记录样本hash、筛选规则、版本和可用scope；删除请求不仅影响源库，还要判断派生数据、checkpoint与adapter的责任边界。权重中的逐用户删除通常比外部知识更难精确操作，因此高变化事实优先留在可更新、可溯源的数据层。",
      "blueprint": {
        "inputs": [
          "样本及用途授权",
          "纠正轨迹和评审",
          "模板schema及保留规则"
        ],
        "steps": [
          "核训练资格去标识",
          "明确目标token及mask",
          "按实体时间分组去重",
          "冻结manifest和删除责任"
        ],
        "outputs": [
          "合格训练数据版本",
          "独立验证集及污染记录"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent评测方法",
          "kind": "official-doc",
          "note": "学习收益需在独立业务任务验证。"
        }
      ],
      "links": [
        {
          "target": "eval-holdout-contamination",
          "type": "requires",
          "reason": "训练集与最终泛化证据隔离。"
        }
      ],
      "en": "Training Data Governance"
    },
    {
      "id": "talk-agentic-surfaces",
      "title": "实践讲座：Agent接口与长任务演进",
      "aliases": [
        "Gagan Bhat",
        "Isabella Kai He",
        "context"
      ],
      "kind": "reference",
      "parentId": "talks-reliability",
      "order": 2,
      "summary": "Anthropic Applied AI讨论API、SDK、托管Agent、durable session与模型变化下的harness适配。",
      "question": "API、loop、执行环境和memory演进，改变了哪些控制边界？",
      "body": "## 讲者与证据边界\nGagan Bhat与Isabella Kai He来自Anthropic Applied AI，在AI Engineer World's Fair 2026讨论Agent接口演进。可完整阅读原发布方31:24的带时间戳逐字稿；本页依据文稿解读，不声称连续观看或复现演示。会议年可核，二级目录中的上传月不作为精确录制日期；厂商性能与自我改进说法保留为其自述。\n\n## 从接口演进看控制边界\n讲座依次讨论API、嵌入harness的SDK和托管基础设施。11:16介绍loop与执行环境解耦；14:46将context视为持久历史的当前视图；27:34谈周期整理memory的dreaming；28:55谈按rubric检查完成的outcomes。它们揭示会话、当前窗口、沙箱和能力配置并非同一个对象。\n\n## 旧模型补丁需要重新验证\n7:31附近讨论harness包含对模型弱点的假设：一种context重置策略，在较新模型上可能变成延迟和缓存负担。工程上应为补丁记录根因、适用版本与删除条件，用旧新模型和旧新harness对照；不因历史上有效就永久保留。供应商托管了harness，也不能省略业务工具、权限和领域验收。\n\n## Memory整理不是权重训练\n周期读取历史并编辑外部memory，可以改变后续可见context，但不等于模型参数学习。团队可借鉴候选经验、来源、冲突、有效期与审查晋升；用未见任务检查净收益，并允许撤销。独立grader提供反馈也不自动提供真值，仍需确定性检查、专家校准与预算停止。\n\n## 可操作的设计问题\n若loop或沙箱单独失败，哪些状态可以恢复？丢弃context后能否从原始日志取回关键证据？新方法和旧memory能否回滚？这些问题比复制某个产品演示更有迁移价值。具体产品状态、区域与访问资格应另看当前产品文档，不能用历史讲座证明今天所有账户可用。",
      "blueprint": {
        "inputs": [
          "模型及harness版本",
          "持久历史与当前context",
          "沙箱memory和grader"
        ],
        "steps": [
          "分API loop执行环境",
          "重评旧补丁和缓存成本",
          "整理memory保留来源",
          "独立任务验证再晋升"
        ],
        "outputs": [
          "恢复和持久化合同",
          "补丁消融及记忆实验"
        ]
      },
      "citations": [
        {
          "url": "https://ai.engineer/talks/K0X9QDRkIdg-anthropics-applied-ai-team-on-evolution-agentic",
          "label": "原发布方完整逐字稿",
          "kind": "talk",
          "note": "文稿分析不代表连续观看、演示复现或现行产品资格。",
          "locator": "7:31 旧补丁；14:46 context；27:34 dreaming；28:55 outcomes"
        },
        {
          "url": "https://www.youtube.com/watch?v=K0X9QDRkIdg",
          "label": "原始视频",
          "kind": "talk",
          "note": "文稿分析不代表连续观看、演示复现或现行产品资格。"
        }
      ],
      "links": [
        {
          "target": "eval-model-migration",
          "type": "complements",
          "reason": "旧模型补丁可能损害新模型。"
        },
        {
          "target": "learning-feedback-flywheel",
          "type": "complements",
          "reason": "memory整理与独立grader形成反馈。"
        }
      ],
      "en": "Agentic Surfaces Talk"
    },
    {
      "id": "talks-feedback",
      "title": "反馈与能力",
      "aliases": [
        "talks-feedback"
      ],
      "kind": "branch",
      "parentId": "talks",
      "order": 2,
      "summary": "可检查目标、数据和评分如何支持持续改进。",
      "question": "这场讲座提出什么机制，哪些结论可迁移到企业设计？",
      "body": "这一组连接可观察目标、反馈数据与持续决策。编码Agent容易获得测试、构建或界面反馈，其他企业任务则需要来源、数值、专业rubric或学习结果；可迁移的是观察、修复与验证结构，而非某个编码基准分数。\n\n先看可检查目标和并行工作区，再看如何定制dataset、scorer及反馈筛选。用户不满意不一定是事实错误，模型判分也不天然是真值。把trace、专家修订、用例和候选发布连接起来，同时保留隐藏持出与独立验收，才能形成可控改进。讲者的团队效率经验不能直接变成所有业务的上线承诺。",
      "blueprint": {
        "inputs": [
          "原始讲座文稿",
          "待设计的企业任务"
        ],
        "steps": [
          "区分讲者主张与证据",
          "抽取可迁移机制",
          "形成可执行验证"
        ],
        "outputs": [
          "设计问题与验收项",
          "证据及适用边界"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent评测方法背景",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "domain-education-workflow",
      "title": "教育Agent诊断与分层提示流程",
      "aliases": [
        "教学Agent",
        "递进提示",
        "学生状态"
      ],
      "kind": "case",
      "parentId": "domains-education",
      "order": 3,
      "summary": "用作答证据形成可纠正的概念观察，按课程目标提供递进提示和迁移练习。",
      "question": "怎样围绕学生作答证据开展教学，而非只输出标准答案？",
      "body": "## 教学目标和学生状态分别定义\n教育Agent应先明确课程、年级、概念目标、教师规则和学生数据授权。课程知识是可版本化内容，学生认知状态是带证据和不确定性的观察，二者不能混为一份通用知识库。一次答错、输入语气或作答速度不足以形成长期能力标签。先规定这一轮要诊断什么、允许怎样帮助，以及什么结果需要教师介入。\n\n## 用少量有区分度的题诊断\n从当前作答识别候选误解，再用针对性问题区分概念问题、计算失误、语言障碍和题意歧义。保存学生原作答、提示条件、模型解释和置信边界，允许教师覆盖候选判断。标准答案也可能错，遇到冲突应先核题目和答案，不让Agent坚持一个错误金标。诊断是提出可验证假设，不是自动医疗或心理标签。\n\n## 递进干预而非固定答题脚本\n先给目标相关的小提示，观察学生独立推进，再增加帮助或示例。数学、代码等可调用确定性工具检查，语言解释用适龄rubric。直接答案策略由作业、复习、无障碍等教学场景决定，不能所有情况固定拒绝。记录提示量和学生下一步行为，避免模型自己完成全部解题后仍将其记成学生掌握。\n\n## 用新任务检查掌握\n当题正确只是第一层；增加无提示同类题、结构变化的迁移题和延迟复习，观察学生能否解释和独立作答。练习题与测验不应只是换数字，同一题库答案不得通过RAG或memory泄漏给测试。完成这一轮可以是明确某个误解、取得后续作答证据和安排复习，而不一定宣布概念已全面掌握。\n\n## 记忆保存可纠正观察\n保存概念、尝试、提示量、证据、时间、教师修订和下次复习建议；允许查看、纠正和按策略撤回。学生私有对话不直接进入团队skill，通用教学方法经过审查和去标识才复用。跨设备与不同学生登录时重新核主体，不能让相似题或共享设备把另一人的状态带入当前学生。\n\n## 何时升级与怎样证明价值\n学生替他人作答、附件缺失、课程版本变化、语言障碍、明显题目歧义或高风险问题，应按产品合同请教师处理并保留缺口。评估既看Agent答案、教学策略和安全，也看学生迁移、延迟保持及教师负担。Tutor CoPilot的研究对象是教师获得AI辅助，其结果不能直接证明全自动Tutor有效；具体产品要用适当的学习效果研究验证。",
      "blueprint": {
        "inputs": [
          "课程目标与年级",
          "授权学生记录",
          "当前作答证据"
        ],
        "steps": [
          "诊断候选误解",
          "递进提示并观察",
          "新题验证独立作答",
          "保存可纠正观察"
        ],
        "outputs": [
          "概念级观察",
          "复习建议与教师待办"
        ]
      },
      "citations": [
        {
          "url": "https://arxiv.org/abs/2410.03017",
          "label": "Tutor CoPilot：人类教师获得AI辅助的研究",
          "kind": "paper",
          "note": "原始资料支持方法背景；本页流程与验收为工程建议。"
        }
      ],
      "links": [
        {
          "target": "domain-education-learning-outcomes",
          "type": "requires",
          "reason": "答对不代表学会。"
        }
      ],
      "en": "Educational Agent Workflow"
    },
    {
      "id": "domains-legal",
      "title": "法律研究",
      "aliases": [
        "domains-legal"
      ],
      "kind": "branch",
      "parentId": "domains",
      "order": 3,
      "summary": "matter资格、法域、原文蕴涵和效力。",
      "question": "这一领域如何定义任务、证据、异常和可验证结果？",
      "body": "法律应用先确认matter、材料资格、合同版本、法域和法律截止日，再建立规则、事实与推论的证据链。草稿、签署版、附件和补充协议分别标识，研究产物、正式意见、对外发送及签署各有责任和批准边界。\n\n先看研究与合同辅助流程，再进入引证、蕴涵和效力验证。真实存在的来源可能不支持结论，支持结论的判例也可能不适用当前法域或已经受到负面处理。缺少合格citator或必要专业复核时，应列未完成层次。RAG改善取证入口，不能自动消除法律幻觉。",
      "blueprint": {
        "inputs": [
          "领域任务与权限"
        ],
        "steps": [
          "确认范围",
          "收集证据",
          "验证结果"
        ],
        "outputs": [
          "产物与未决项"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：按Agent任务设计评测",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "eval-trial-replay",
      "title": "Trial快照与可重放实验",
      "aliases": [
        "试验快照",
        "重放",
        "Trial"
      ],
      "kind": "concept",
      "parentId": "evaluation-data",
      "order": 3,
      "summary": "把模型、harness、数据、权限和执行资源记录为同一个实验条件，恢复case初态以隔离污染。",
      "question": "一次Agent试验需要冻结什么，才能公平比较和排查失败？",
      "body": "## 一个Trial不仅是一段输出\nTrial是某个用例在一组固定条件下的一次尝试。除模型ID，还要记录harness提交、prompt、工具schema、采样与reasoning参数、数据和索引快照、memory初态、权限版本、执行镜像、资源、网络策略和预算。否则相同问题分数变化时，很难判断是模型变好、数据更新、权限变化还是运行环境不同。\n\n## 恢复声明的初态\n每次运行恢复case指定快照，清除其他Trial留下的文件、数据库写入、历史答案和git记录。记忆评测可以预置前序session，缓存评测可以预热，但应明确记录这些状态，分别报告cold和warm条件。隔离的目标是防止无意污染，并非把所有case一律清空为失忆Agent。涉及真实外部系统的测试优先使用快照、模拟或独立测试租户。\n\n## 把轨迹、产物与判分连起来\n保留公开可取得的消息、工具请求与结果、状态转换、产物内容hash、最终业务状态和费用。Grade关联trial_id、grader版本、证据引用、pass/fail/unknown以及人工裁决。无需要求不可获得的私有思维链；可审计性来自行动证据和权威状态。判分器与被测Agent应有不同写权限，避免Agent修掉测试本身。\n\n## 可重放不等于逐字复现\n远程模型可能不提供固定snapshot，即使有seed也未必完全确定；时间、服务负载和工具依赖还会变化。区分“能重建条件并重新测量”和“字节级相同”。端到端失败需保留，另做模型错误与基础设施故障归因。官方基础设施实验显示资源约束会改变Agent基准表现；本页建议是把这些变量纳入实验合同，不能用删掉失败样本来美化产品成功率。\n\n## 重放不等于再次请求同一句话\n一个法律研究任务依赖当时的文档版本、搜索索引、客户权限和工具响应。若重跑时网页已经更新，分数变化可能来自数据而非模型。可将工具响应录制后回放以隔离推理差异，再用实时工具测试环境适应，两者分开命名。录制内容要有脱敏、访问与保留范围；未固定的服务端行为列入复现限制。基础设施失败保留原始事件，再按预先规则重试或单独报告，不能默默丢弃失败样本。",
      "blueprint": {
        "inputs": [
          "EvalCase和AgentRelease",
          "工具及memory初态",
          "缓存预置和随机设置"
        ],
        "steps": [
          "恢复隔离初态",
          "执行并记录逐步事件",
          "封存产物与外部终态",
          "独立评分及归因infra错误"
        ],
        "outputs": [
          "Trial快照与轨迹",
          "Grade和复现限制"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc",
          "note": "2026-01-09；官方方法背景，具体合同与阈值须按业务验证。"
        },
        {
          "url": "https://www.anthropic.com/engineering/infrastructure-noise",
          "label": "Anthropic：基础设施噪声实验",
          "kind": "official-doc",
          "note": "2026-02-05；资源影响属于厂商实验，不外推固定幅度。"
        }
      ],
      "links": [
        {
          "target": "eval-case-contract",
          "type": "requires",
          "reason": "初态、终态与判分需要同一合同。"
        }
      ],
      "en": "Trial Replay"
    },
    {
      "id": "evaluation-grading",
      "title": "评分与验证",
      "aliases": [],
      "kind": "branch",
      "parentId": "evaluation",
      "order": 3,
      "summary": "组合确定性检查、语义评分与专家校准。",
      "question": "如何把这项机制变成可执行、可核查的工程合同？",
      "body": "评分方法按问题选用：结构、算术和权威状态优先用确定性检查；开放语义任务用明确rubric；法律适用、教学策略和严重遗漏需要专家标准。三者形成互补证据，不以多个模型互相赞同代替外部真值。\n\n阅读路径先确定可执行验证的范围，再设计能引用证据并保留unknown的Judge，最后用独立专家标签校准漏判和误判。规则、模型与阈值都要版本化，更换评分器后检查历史可比性。硬权限和严重错误作为单独门禁，不能被流畅度、文风等软分抵消；验证器自身失败也必须区别于被测任务失败。",
      "blueprint": {
        "inputs": [
          "业务目标与约束"
        ],
        "steps": [
          "明确适用范围",
          "选择可执行检查",
          "保留结果与证据"
        ],
        "outputs": [
          "可审阅的设计合同"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc",
          "note": "2026-01-09；官方方法背景，具体合同与阈值须按业务验证。"
        }
      ],
      "links": []
    },
    {
      "id": "learning-sft",
      "title": "SFT与工具轨迹监督",
      "aliases": [
        "SFT",
        "监督微调",
        "工具轨迹"
      ],
      "kind": "concept",
      "parentId": "learning-training",
      "order": 3,
      "summary": "通过合格示例训练稳定格式、抽取与工具行为，并保持与实际消息模板和工具协议一致。",
      "question": "怎样用合格轨迹教稳定行为，并证明超越prompt基线？",
      "body": "## SFT教的是被监督的行为\n监督微调用合格输入与目标输出训练模型，适合稳定字段抽取、领域格式、工具选择、证据不足时退让和教学提示风格。它不保证模型学会最新法律事实或未来价格，也不替代检索权限。先明确要减少的稳定行为错误，确保样本目标比当前输出更可靠，而非仅因文字漂亮就进入训练。\n\n## 多步Agent需要对齐真实协议\n完整轨迹要保留工具请求、结果和恢复的关系，并与线上chat template及schema一致。检查assistant-only或completion-only等loss masking是否实际生效，尤其不要让模型背诵工具返回中的私人事实。用于SFT的失败案例应改成正确处理过程；未纠正错误可作诊断或偏好负例，不能不加区分作为正向示范。\n\n## 训练参数跟随学习曲线\n固定基座revision、tokenizer、数据manifest、模板、代码和依赖，记录序列长度、batch、学习率、epoch、精度、seed、资源和费用。先在小规模高质量样本上观察学习曲线，避免用固定“几千条就够”取代任务分析。验证格式、工具行为、拒答和跨域能力，训练loss下降仅说明拟合目标改善。\n\n## 用完整Harness决定是否有价值\n比较base加原prompt、base加改进prompt、SFT候选加相同prompt，在同一任务、数据和预算下多次运行。检查未见任务、严重错误、人工修订、成本和P95；训练之后仍可能依赖旧工具协议而退化。发布包含基座、adapter、模板与serving配置，量化或合并adapter后重新评测。TRL文档提供训练接口，实际业务效果须通过自己的合同验证。",
      "blueprint": {
        "inputs": [
          "合格输入目标轨迹",
          "固定base和模板",
          "assistant目标mask"
        ],
        "steps": [
          "对齐call/result协议",
          "训练并观测学习曲线",
          "比较base和prompt基线",
          "评持出回归及完整harness"
        ],
        "outputs": [
          "SFT权重或adapter",
          "收益退化及训练manifest"
        ]
      },
      "citations": [
        {
          "url": "https://huggingface.co/docs/trl/main/en/sft_trainer",
          "label": "SFT与工具轨迹监督：原始文档",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "learning-data-contract",
          "type": "requires",
          "reason": "监督目标需有资格、版本和纠正。"
        }
      ],
      "en": "Supervised Fine-Tuning"
    },
    {
      "id": "learning-training",
      "title": "权重训练",
      "aliases": [
        "learning-training"
      ],
      "kind": "branch",
      "parentId": "learning",
      "order": 3,
      "summary": "监督、偏好、参数高效适配与奖励优化。",
      "question": "如何积累可迁移能力并保留可验证的发布边界？",
      "body": "这里分别展开训练目标、参数方式和能力迁移，避免把SFT、LoRA、DPO与GRPO当成同一维度的互斥选项。SFT学习监督行为，DPO学习偏好，RL优化奖励，GRPO是RL中的算法选择；LoRA与QLoRA改变适配和资源路径，蒸馏则利用教师输出或反馈训练学生。\n\n阅读时先确定数据和目标，再看参数与算力，最后核独立验证及部署限制。所有方法都可能放大错误标签、未来泄漏或奖励漏洞。论文和框架提供实现入口，不能直接承诺企业收益；完整任务的严重错误、成本和回归结果决定是否晋升。",
      "blueprint": {
        "inputs": [
          "目标能力与合格数据"
        ],
        "steps": [
          "定位缺口",
          "提出并验证候选",
          "受控发布"
        ],
        "outputs": [
          "版本化能力与评测证据"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent评测方法",
          "kind": "official-doc",
          "note": "学习收益需在独立业务任务验证。"
        }
      ],
      "links": []
    },
    {
      "id": "talk-feedback-verification",
      "title": "实践讲座：可检查目标与编码Agent",
      "aliases": [
        "Boris Cherny",
        "Claude Code",
        "可检查目标"
      ],
      "kind": "reference",
      "parentId": "talks-feedback",
      "order": 3,
      "summary": "Boris Cherny讨论通用入口、项目上下文、可检查输出与并行工作区如何支持反馈循环。",
      "question": "可检查目标与并行工作区，如何迁移到企业Agent任务？",
      "body": "## 原始材料与时间边界\nBoris Cherny在AI Engineer World's Fair 2025的《Claude Code & the evolution of agentic coding》中讨论编码交互、通用工具和可检查反馈。原发布方提供完整带时间戳逐字稿，页面时长18:12；本页依据全文文字作观点解读，不代表连续观看或复现演示。2025年的命令和功能入口仅作历史背景，实际接口应查现行文档。\n\n## 可检查目标支持迭代\n14:54附近强调给Agent可观察的输出目标；17:26讨论多checkout或worktree并行。工程上可以把单元测试、集成结果、浏览器截图或真实设备反馈作为不同验证信号，但它们证明的层次不同。编译通过不是业务正确，截图也不是完整交互或长期运行证明。\n\n## 通用入口应配清晰合同\n终端和可组合工具让模型接触真实环境，却同时扩大文件、网络和副作用边界。项目说明应短、可定位、按需加载；工具返回要让模型能回查证据。先探索再计划可适合复杂任务，但计划要随新证据修订，不能机械增加一次planner就认为可靠。最终仍需要独立验收和显式停止条件。\n\n## 并行不是合并策略\n多个工作区有助隔离写入，但仍需任务归属、共享接口、产物、整合负责人和版本记录。父Agent接收证据与结果，不能只合并几个自信摘要。并行收益应看关键路径和总成本；同一模型、同源材料的错误不因角色名称不同而独立。写同一资源时还需权限、锁或乐观版本。\n\n## 从编码迁移到企业工作\n研究报告可以用来源与数值复算，法律草稿可以用原文和专业rubric，教育可以用独立作答与迁移题建立反馈。迁移的是目标、观察、修复、验证的结构，不是把编码测试分数当成其他领域质量。Latent Space的2025-05-07访谈可作相关产品背景；其部分文稿信息不作为本页新的实测依据。",
      "blueprint": {
        "inputs": [
          "可观察输出目标",
          "权限与隔离工作区",
          "测试界面或领域证据"
        ],
        "steps": [
          "探索并修订计划",
          "执行观察独立反馈",
          "预算内修复重验证",
          "整合并行产物未决项"
        ],
        "outputs": [
          "可检查交付与证据",
          "验证层次和整合规则"
        ]
      },
      "citations": [
        {
          "url": "https://ai.engineer/talks/Lue8K2jqfKk-claude-code-evolution-agentic-coding",
          "label": "原发布方完整逐字稿",
          "kind": "talk",
          "note": "文稿分析不代表连续观看、演示复现或现行产品资格。",
          "locator": "14:54 可检查目标；17:26 并行工作区"
        },
        {
          "url": "https://www.youtube.com/watch?v=Lue8K2jqfKk",
          "label": "原始视频",
          "kind": "talk",
          "note": "文稿分析不代表连续观看、演示复现或现行产品资格。"
        },
        {
          "url": "https://www.latent.space/p/claude-code",
          "label": "相关访谈：仅作背景",
          "kind": "talk",
          "note": "文稿分析不代表连续观看、演示复现或现行产品资格。"
        }
      ],
      "links": [
        {
          "target": "eval-task-outcome",
          "type": "complements",
          "reason": "可检查目标为循环提供反馈。"
        }
      ],
      "en": "Verifiable Goals Talk"
    },
    {
      "id": "domain-education-learning-outcomes",
      "title": "教学正确性、迁移与学习效果",
      "aliases": [
        "迁移",
        "延迟保持",
        "教育评测"
      ],
      "kind": "case",
      "parentId": "domains-education",
      "order": 4,
      "summary": "将Agent答题、教学行为、学生即时表现、延迟保持和实际学习增益分层验证。",
      "question": "怎样区分Agent会答题、学生当场答对和真正学会？",
      "body": "## 区分系统会做与学生学会\n教育效果至少分五层：Agent自身答题正确、互动和提示策略、学生当场表现、迁移与延迟保持，以及师生负担和长期结果。模型输出标准答案只是第一层；学生在充分提示下答对，也不能直接记成独立掌握。聊天满意度和使用时长可以提供体验信号，却不能替代学习增益。\n\n## 先核正确性和教学过程\n对数学、代码、单位和步骤使用确定性验证，检查题目和标准答案质量。教师rubric评估误解诊断、提示是否泄题、解释是否适龄、是否适时求助以及不同基础学生能否受益。将提示量、原作答、修改和最终结果连成轨迹，避免只看最后一条正确回答。教师覆盖模型判断应保留理由和证据。\n\n## 设计真正未见的测量\n按学生、班级、学校与题型家族划分数据，避免同一人的相近session或一道题的数字改写跨越训练与test。前后测使用等值新题，迁移题检验结构理解，延迟测量观察保持。测试期间控制RAG、memory和教师提示可见范围，记录缺席与未完成，不把只有愿意继续使用的人留下来计算效果。\n\n## 用合适实验估计因果效果\n上线后可采用适当随机试验或分阶段设计，预先写主要学习指标、样本预算、观察期与停止规则。按学生、教师或班级等实际实验单位处理相关性，报告分组基线、差异区间和缺失情况。只比较自愿使用者与未使用者会混入动机、基础和教学资源差异，不能直接解释为Agent带来的效果。\n\n## 研究来源有适用边界\nTutor CoPilot论文研究教师在实时辅导中获得AI支持，提供了测学生掌握和教学行为的例子；它不是对任意学科、年龄或全自动教学的保证。其他研究的模型、提示、课程、教师和任务不同，不能搬用一个增益百分比作为产品承诺。先复现适用测量，再在自己的场景中建立证据。\n\n## 发布和持续观察\n把题库、课程版本、模型、教学策略、student-state schema与评分器纳入发布合同。看总体效果也看弱基础、语言不同和特殊需要等合适切片，避免平均改善掩盖局部伤害。若版本更会给答案却降低独立作答或增加教师负担，应重新设计干预，而非仅优化点赞率。所有数据使用、标签和保留遵守明确资格与纠正流程。\n\n观察窗口、缺失处理与评分规则应在试验前冻结，结果解释同时保留不确定性。",
      "blueprint": {
        "inputs": [
          "教学合同与题型家族",
          "等值前后测及迁移题",
          "实验分组与提示记录"
        ],
        "steps": [
          "核答案和教学rubric",
          "隔离题库与用户泄漏",
          "测迁移和延迟保持",
          "聚类分析并抽审"
        ],
        "outputs": [
          "学习效果与区间",
          "分组表现和适用边界"
        ]
      },
      "citations": [
        {
          "url": "https://arxiv.org/abs/2410.03017",
          "label": "Tutor CoPilot：学习结果与教学行为",
          "kind": "paper",
          "note": "原始资料支持方法背景；本页流程与验收为工程建议。"
        }
      ],
      "links": [
        {
          "target": "eval-statistical-confidence",
          "type": "requires",
          "reason": "学习效果实验按学生或班级聚类。"
        }
      ],
      "en": "Learning Outcomes"
    },
    {
      "id": "eval-harness-fidelity",
      "title": "工具、Loop、Harness与产品四层评测",
      "aliases": [
        "L0",
        "L1",
        "L2",
        "L3",
        "保真度"
      ],
      "kind": "concept",
      "parentId": "evaluation-targets",
      "order": 4,
      "summary": "同一模型在简单工具循环中通过，不代表在真实产品的上下文、权限与界面中通过。",
      "question": "工具单测通过后，还要验证哪些完整产品边界？",
      "body": "## 小循环分数为什么不能直接上线\n一个工具在直接调用时正确，并不说明模型会选它；模型在简化循环里会选它，也不说明真实产品中的工具发现、压缩、权限和界面会工作。OpenAI的插件评测示例将直接工具测试、独立function-calling循环和产品harness分开，强调测到的是模型与周边配置的组合。企业验收还需要补用户侧产品边界。\n\n## 四层测试各有职责\nL0将结构化参数直接发给工具，测解析、过滤、分页、超时和幂等。L1给自然语言任务，让模型选择工具及参数，定位schema和指令问题。L2运行真实prompt合并、tool search、memory、session、workflow、审批、重试和子Agent。L3通过真实产品入口检查消息渲染、产物访问、跨设备恢复、用户权限和人工接管。高层失败时用低层结果定位原因，而非以低层通过替代高层验收。\n\n## 保持输入和边界可比\n各层使用同一组任务意图、数据版本和成功合同；明确简化层省略了什么。相同模型在不同harness中可见工具、上下文预算及停止规则不同，分数不能混成单一排行榜。记录每层资源和费用，避免将更长时间或更多尝试误写为模型独立提升。\n\n## 检查真实交付\n典型层间故障包括：工具说上传成功但链接无权限；生成回复已显示却没有写入会话；手机恢复后丢失要求；草稿被界面误标为已发送。L3应核用户实际关心的终态，并保留回执。公开示例或厂商演示只能说明该设计可讨论，不能证明自有租户已经通过。生产候选至少在完整harness中评测，再以受控真实流量检验产品差距。\n\n## 用相同故障跨层定位\n例如报告生成器能直接导出正确文件，工具层可通过；自然语言任务却选择错误模板，问题可能在模型或描述；运行重启后找不到文件，是持久化边界；界面链接过期，是产品交付边界。每层使用同一合同的相关部分，并记录覆盖矩阵。模拟工具便于快速迭代，真实连接器可发现授权、分页和限流差异，两类结果都要留存，不能用模拟全绿替代真实环境资格。",
      "blueprint": {
        "inputs": [
          "同一任务合同",
          "工具和真实权限",
          "完整运行环境"
        ],
        "steps": [
          "L0直接测工具合同",
          "L1测模型工具循环",
          "L2测恢复、memory和harness",
          "L3测审批和用户交付"
        ],
        "outputs": [
          "各层失败定位",
          "完整产品资格及覆盖缺口"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/cookbook/examples/partners/harness_aware_plugin_evals/harness_aware_plugin_evals",
          "label": "工具、Loop、Harness与产品四层评测：一手资料",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "eval-trial-replay",
          "type": "requires",
          "reason": "各保真层应共享可比输入和实验记录。"
        },
        {
          "target": "agent-harness",
          "type": "verifies",
          "reason": "检验恢复、权限与交付等完整运行边界。"
        }
      ],
      "en": "Evaluation Fidelity"
    },
    {
      "id": "evaluation-statistics",
      "title": "统计与泛化",
      "aliases": [],
      "kind": "branch",
      "parentId": "evaluation",
      "order": 4,
      "summary": "衡量重复可靠性、不确定性与未见任务表现。",
      "question": "如何把这项机制变成可执行、可核查的工程合同？",
      "body": "本分支处理分数应如何解释，而不是替业务定义成功。先区分至少一次成功的pass@k与全部成功的pass^k，再看有限样本和相关试验下的不确定性，最后检查数据是否支持真正未见任务上的泛化声明。\n\n同一任务多次尝试、同一学生多个会话和同一报告的改写通常有关联，不能当成完全独立样本。报告分母、实验单位、预算、置信区间、严重错误和切片；隐藏持出集防止反复优化的选择偏差。金融任务还要识别模型参数知道未来的泄漏。统计证据描述观察到的分布，不能证明所有未来情境均安全。",
      "blueprint": {
        "inputs": [
          "业务目标与约束"
        ],
        "steps": [
          "明确适用范围",
          "选择可执行检查",
          "保留结果与证据"
        ],
        "outputs": [
          "可审阅的设计合同"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc",
          "note": "2026-01-09；官方方法背景，具体合同与阈值须按业务验证。"
        }
      ],
      "links": []
    },
    {
      "id": "learning-improvement",
      "title": "持续改进",
      "aliases": [
        "learning-improvement"
      ],
      "kind": "branch",
      "parentId": "learning",
      "order": 4,
      "summary": "技能候选晋升与证据驱动闭环。",
      "question": "如何积累可迁移能力并保留可验证的发布边界？",
      "body": "持续改进的核心不是让Agent自由改写自己，而是让真实问题有一条通向可验证候选能力的路径。用户反馈先经去噪和专业判断，新增用例及证据，再按根因改工具、知识、prompt、memory、skill或权重。\n\n先看反馈闭环，理解从trace到候选diff的关联；再看skill晋升，给方法写清来源、前提、scope、测试和失效条件。优化器可访问开发证据，正式持出与发布规则保持独立。反复迭代后还需fresh audit，以防开发集过拟合。被否决的候选也留下原因，正式版本保留撤销、回退和后续观测。",
      "blueprint": {
        "inputs": [
          "目标能力与合格数据"
        ],
        "steps": [
          "定位缺口",
          "提出并验证候选",
          "受控发布"
        ],
        "outputs": [
          "版本化能力与评测证据"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent评测方法",
          "kind": "official-doc",
          "note": "学习收益需在独立业务任务验证。"
        }
      ],
      "links": []
    },
    {
      "id": "learning-lora",
      "title": "LoRA参数高效适配",
      "aliases": [
        "LoRA",
        "adapter",
        "低秩"
      ],
      "kind": "concept",
      "parentId": "learning-training",
      "order": 4,
      "summary": "将LoRA理解为参数化方法而非训练目标，明确基座、adapter与服务配置的组合关系。",
      "question": "LoRA解决哪类参数与发布成本问题，为何不是训练目标？",
      "body": "## 参数化方法与训练目标分开\nLoRA通过低秩adapter更新部分有效参数，使训练和发布不必总保存完整改写的基座。它是参数高效适配方法，不是与SFT、DPO并列的任务目标；同一种参数化方式可以服务不同训练目标。模型是否更懂领域，仍取决于数据、目标和验证，而不是使用adapter本身。\n\n## 明确基座和可训练范围\n记录基座revision、目标模块、rank、缩放、dropout和可训练参数列表，核实这些模块确实存在且被更新。选择范围应通过实验决定，不能把某个模型家族的配置直接搬到另一架构。训练数据、tokenizer、chat template与工具协议仍需对齐，LoRA不会自动修复数据错误或权限设计。\n\n## 服务端要知道加载了哪个Adapter\n发布记录基座与adapter的兼容关系、文件hash、依赖、精度及serving参数。多adapter端点必须把租户资格和路由显式绑定，防止把另一客户的adapter用于当前请求。KV cache是否可跨adapter复用由具体引擎语义决定，不应默认共享。合并adapter后再运行回归，不能假设合并和量化完全无影响。\n\n## 比较完整成本与质量\n减少可训练参数可能降低部分训练资源和checkpoint体积，但总显存仍包含基座、激活、优化器、序列与batch等因素；不宜承诺一张卡必然可训。比较全量微调、LoRA和API基线时，用同一持出任务与业务指标衡量质量、延迟、GPU利用率和维护投入。若领域收益不稳定，保留adapter作为候选而非直接替代正式模型。",
      "blueprint": {
        "inputs": [
          "固定base revision",
          "目标和合格数据",
          "目标模块及资源预算"
        ],
        "steps": [
          "选rank缩放和训练范围",
          "核模块实际更新",
          "绑定serving兼容",
          "比质量资源及租户路由"
        ],
        "outputs": [
          "低秩adapter和依赖",
          "合并前后资格与成本"
        ]
      },
      "citations": [
        {
          "url": "https://huggingface.co/docs/peft/main/package_reference/lora",
          "label": "LoRA参数高效适配：原始文档",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "learning-sft",
          "type": "complements",
          "reason": "LoRA可参数化SFT，也可用于其他目标。"
        }
      ],
      "en": "Low-Rank Adaptation"
    },
    {
      "id": "talk-eval-engineering",
      "title": "实践讲座：Eval如何支持产品决策",
      "aliases": [
        "Ankur Goyal",
        "Braintrust",
        "eval"
      ],
      "kind": "reference",
      "parentId": "talks-feedback",
      "order": 4,
      "summary": "Ankur Goyal讨论定制数据与scorer、工具上下文、新模型机会和用户反馈的人工筛选。",
      "question": "怎样将数据、scorer和真实反馈变成产品决策机制？",
      "body": "## 讲座资料与适用范围\nAnkur Goyal在AI Engineer World's Fair 2025的《Five Hard-Earned Lessons About Evals》中讨论数据、scorer、context和产品迭代。原发布方提供19:46的完整逐字稿；本页基于全文文字解读，不声称连续观看或独立复现其内测。确切上传日未核，厂商产品图表和分数只代表讲者当时报告，不用于估计其他团队ROI。\n\n## 数据与评分器是产品规范\n2:10附近强调定制dataset与scorer，4:05讨论工具如何构成模型看到的context。对企业Agent，不能只修改system prompt，再套一个通用judge。任务合同应规定证据、允许变化和严重错误；工具输出大小、命名、分页及错误反馈也进入实验，避免高分只是测到了另一种简化系统。\n\n## 反馈需要领域判断\n14:36附近讨论把用户反馈纳入评测时的筛选，17:33区分不满意与答错。可操作做法是先保留原任务、证据与修订，再让专家决定是否成为正式case。负反馈可能针对结果本身，点赞可能受到篇幅和语气影响；自动全部收录会产生噪声和错误优化目标。\n\n## 为尚未可行的能力保留测试\n能力集可以包含目前模型完成不好的任务，以便新模型出现时及时判断机会；回归集则保护既有承诺。评测促进快速决策，但不能把某团队能迅速升级当成所有业务都应在一天内上线的SLA。应统一任务和预算、保留持出，观察模型与harness交互、成本和风险。\n\n## 闭环的工程含义\n将trace、专家反馈、用例、grader、候选diff与发布资格连起来，优化整个系统而非只优化一句提示。模型可提出数据缺口和评分器改进，但最终test、权限和晋升边界要保持独立。评价进步时同时看新能力、回归、审阅时间与严重错误；不以训练或内测分数上涨替代真实业务结果。",
      "blueprint": {
        "inputs": [
          "任务合同与失败",
          "领域专家候选scorer",
          "trace及用户反馈"
        ],
        "steps": [
          "定制数据和评分",
          "将工具context纳入实验",
          "筛反馈形成新case",
          "持出比较候选后发布"
        ],
        "outputs": [
          "数据评分发布闭环",
          "能力集和回归集演进"
        ]
      },
      "citations": [
        {
          "url": "https://ai.engineer/talks/a4BV0gGmXgA-five-hard-earned-lessons-about-evals",
          "label": "原发布方完整逐字稿",
          "kind": "talk",
          "note": "文稿分析不代表连续观看、演示复现或现行产品资格。",
          "locator": "2:10 定制评分；14:36 反馈筛选；17:33 满意度"
        },
        {
          "url": "https://www.youtube.com/watch?v=a4BV0gGmXgA",
          "label": "原始视频",
          "kind": "talk",
          "note": "文稿分析不代表连续观看、演示复现或现行产品资格。"
        }
      ],
      "links": [
        {
          "target": "eval-dataset-curation",
          "type": "complements",
          "reason": "任务数据与scorer需要定制。"
        }
      ],
      "en": "Evaluation Engineering Talk"
    },
    {
      "id": "domain-legal-workflow",
      "title": "法律研究与合同辅助流程",
      "aliases": [
        "法律研究",
        "合同",
        "Matter"
      ],
      "kind": "case",
      "parentId": "domains-legal",
      "order": 5,
      "summary": "先确定matter、法域、时点和合同版本，再完成权威取证、适用分析、redline和专业复核。",
      "question": "法律研究与合同辅助怎样连接权威证据、草稿和专业复核？",
      "body": "## 从Matter、法域和时点开始\n法律Agent先确认客户matter、可访问材料、合同版本、适用法域、法律截止日与输出用途。草稿、签署版、附件和补充协议分别标识，缺失材料明确列出。访问资格由系统验证，不能因为用户在prompt中写了客户名就取得该客户资料。研究草稿、正式法律意见、对外发送与签署是不同动作，各有明确责任和批准边界。\n\n## 先建权威证据链\n搜索法律文本和权威判决，再按需要读取二手解释；新闻和博客不能与法条、判决视作同级权威。每条引证绑定案件或法规实体、原文位置、版本、法院与日期。需要最新状态时从有资格来源获取，不能依靠模型参数中记得的旧法律。搜索覆盖不足时保留范围和缺口，不用整齐完整的段落掩盖未知。\n\n## 分开规则、事实与推论\n将问题拆成规则、客户事实、适用分析、例外和风险，引用的原命题与Agent推论分别保存。合同修改展示原文、候选redline、交叉引用影响和理由；金额、期限、通知窗口等交给结构化校验。不同的合理改写可并存，验收看风险和指令，不必强求唯一措辞。\n\n## 分层验证再请专业复核\n引用存在只是第一层，还需判断是否真正支持命题、适用地域与时间、约束力、后续处理和关键反例。缺少可信citator时，不得宣称已完成效力核查。确定性检查处理案号、法条、日期、交叉引用和数值；语义judge辅助发现覆盖问题，领域专家裁决适用与高风险遗漏。将具体证据和未决点交给审阅者，避免笼统的一键通过。\n\n## 交付与经验沉淀\n产物包含比较或redline、研究memo、引用、验证结果和未决事项。保存草稿不等于获准发布；文件下载、收件权限与外部交付也要核实。matter事实不进入其他客户memory，通用审阅方法经去标识和审查后才进入团队skill。新修法、新合同版本和新增事实触发新任务或版本，旧结论保留当时依据并标注可能过时。\n\n## 异常是产品的一部分\n真实引用不支持结论、判例被区分或推翻、法规尚未生效、附件缺失、特权材料混入共享知识、用户遗漏法域，都应产生可解释暂停或限定结论。RAG能改善取证，但并不自动消除法律幻觉。此流程是研究与辅助系统蓝图，其专业结论仍按适用的律师和组织流程确认，不能从通过格式检查推导法律质量已获保证。",
      "blueprint": {
        "inputs": [
          "Matter与权限",
          "合同版本与附件",
          "法域、时点和用途"
        ],
        "steps": [
          "取得权威证据",
          "分开规则事实与推论",
          "生成差异和风险清单",
          "效力核查与专业复核"
        ],
        "outputs": [
          "Redline与研究memo",
          "引证、验证和未决项"
        ]
      },
      "citations": [
        {
          "url": "https://law.stanford.edu/wp-content/uploads/2024/05/Legal_RAG_Hallucinations.pdf",
          "label": "Stanford：法律RAG可靠性研究",
          "kind": "paper",
          "note": "原始资料支持方法背景；本页流程与验收为工程建议。"
        }
      ],
      "links": [
        {
          "target": "domain-legal-authority-verification",
          "type": "requires",
          "reason": "存在、蕴涵和效力是不同层验收。"
        }
      ],
      "en": "Legal Agent Workflow"
    },
    {
      "id": "eval-task-outcome",
      "title": "任务完成与业务结果评测",
      "aliases": [
        "任务成功率",
        "业务终态",
        "交付验证"
      ],
      "kind": "concept",
      "parentId": "evaluation-targets",
      "order": 5,
      "summary": "以目标、完整产物、政策条件、禁止副作用和可重放证据共同定义任务成功。",
      "question": "怎样区分回答好看、任务完成和用户真正获得结果？",
      "body": "## 结果是业务状态和可用产物\n任务成功不只指Agent说“完成”。对于研究，要有可访问的报告、来源和未决项；对于内部更新，要在权威系统读到新状态；对于通知，要区分生成、提交、送达与用户可见。先确定验收边界，再决定哪些证据足够。HTTP成功、文件存在或文本流畅都只是局部信号。\n\n## 成功条件采用组合判定\n建议将业务目标、必需产物、权限与政策、禁止副作用和证据可重放设为独立维度。高风险硬条件全部满足后，再判断开放内容的覆盖与质量。保留成功、部分完成、等待输入、主动拒绝、超时和失败等原因，分别报告其占比。一个请求因缺少必要证据而正确暂停，可以是安全行为，但不能虚报业务目标已经完成。\n\n## 让评价接近实际使用\n产物检查除schema外，还要确认内容非空、关键数字可复算、引用可访问、下载可打开、适用时点正确。由专业用户抽样判断是否可以用于下一步，并记录审阅、修订、返工和升级所耗时间。满意度与正确性分开：用户不喜欢一个税务或投资结论，并不证明它错误；点赞也可能来自自信文风。\n\n## 防止总分掩盖严重缺陷\n同时报告任务成功率、严重错误率、未完成率、人工介入率、每成功任务成本和尾延迟。按风险、任务家族和角色切片，不让高频简单问答冲淡低频重大错误。固定验收合同版本，变更后保留新旧口径对照。该体系是业务设计建议，具体阈值要由领域owner和样本不确定性决定，不能把一个通用百分比当作所有Agent的上线标准。\n\n## 记录分母和结束原因\n将完成、部分完成、正确暂停、用户取消、超时、工具故障和严重失败分别计数，声明哪些进入主要成功率分母。需要人工补齐才能用的产物，不能与无需修改的交付合并成同一个成功桶。若系统承诺先准备草稿，正确待审批可以是成功终态；若承诺已送达，则必须检查收件侧证据。合同变化会改变成功定义，历史成绩应保留原版本。",
      "blueprint": {
        "inputs": [
          "终态和交付合同",
          "产物与外部状态",
          "用户可见交付证据"
        ],
        "steps": [
          "验证目标真实完成",
          "检查副作用与超时",
          "语义评分保留unknown",
          "核修订成本及交付"
        ],
        "outputs": [
          "任务成功及严重错误",
          "业务价值和审阅负担"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc",
          "note": "2026-01-09；官方方法背景，具体合同与阈值须按业务验证。"
        }
      ],
      "links": [
        {
          "target": "eval-deterministic-verifier",
          "type": "requires",
          "reason": "终态与副作用通过可执行检查提供证据。"
        },
        {
          "target": "eval-llm-judge",
          "type": "complements",
          "reason": "语义Judge是可选评分方式；也可使用专家标注与确定性验证，不把它作为所有任务的必要条件。"
        }
      ],
      "en": "Task Outcome"
    },
    {
      "id": "evaluation-release",
      "title": "发布与运营",
      "aliases": [],
      "kind": "branch",
      "parentId": "evaluation",
      "order": 5,
      "summary": "把离线证据连接模型升级、真实流量与回滚。",
      "question": "如何把这项机制变成可执行、可核查的工程合同？",
      "body": "离线提升只是发布证据的一部分。这里从模型和harness的四格升级实验开始，继续检验路由与故障备援，再进入无真实副作用的shadow和受控真实干预的canary，最终以完整release及回滚合同收束。\n\n每一步都有进入条件、资源预算、严重错误护栏和退出规则。模型、prompt、工具、workflow、memory策略与验证器共同组成发布版本；动态数据和授权另记在run。回退配置不会自动撤销已发生的业务动作或记忆写入，因此需要兼容、补偿和独立恢复验证。供应商无法固定snapshot时，要明确复现限制并持续监测关键用例。",
      "blueprint": {
        "inputs": [
          "业务目标与约束"
        ],
        "steps": [
          "明确适用范围",
          "选择可执行检查",
          "保留结果与证据"
        ],
        "outputs": [
          "可审阅的设计合同"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc",
          "note": "2026-01-09；官方方法背景，具体合同与阈值须按业务验证。"
        }
      ],
      "links": []
    },
    {
      "id": "learning-qlora",
      "title": "QLoRA与训练显存预算",
      "aliases": [
        "QLoRA",
        "4-bit",
        "显存"
      ],
      "kind": "concept",
      "parentId": "learning-training",
      "order": 5,
      "summary": "用量化基座降低训练资源需求，同时按序列、batch、优化器与实际硬件估算内存。",
      "question": "量化基座训练的资源收益和部署质量应怎样实测？",
      "body": "## 量化基座上的Adapter训练\nQLoRA路线使用量化基座减少训练资源需求，同时学习adapter。它与LoRA的联系是参数适配，与低比特推理的联系是表示和资源；这些选择都不保证任务精度不变。基座量化、训练目标、adapter以及最终部署精度应分别进入实验记录，不能只用“4bit”描述完整训练方案。\n\n## 显存预算不能只看参数量\n估算基座权重、量化元数据、adapter、激活、梯度、优化器、临时buffer和框架开销，并用真实序列长度与batch试跑。长context或多步轨迹会改变激活和吞吐，峰值内存比平均值更重要。记录硬件、kernel、精度、gradient checkpointing及失败恢复，不依据网上单例宣称某张卡必然支持某个企业训练集。\n\n## 数据和协议要求没有放松\n量化不降低对样本资格、专家纠正、loss masking和持出划分的要求。工具轨迹仍需匹配目标模型模板与schema。领域中少数关键数字、否定、引证或拒答退化，可能被总体loss和平均分掩盖，应设独立高风险回归切片，并检查是否需要不同精度或其他方法。\n\n## 部署路径逐步验证\n训练后的adapter可保留独立加载，也可根据支持方式合并，再按目标引擎部署。每次合并、重新量化、模板或serving版本变化都重测完整harness，比较基线质量、尾延迟和每成功任务费用。节省训练显存不等于生产一定便宜，小流量、冷启动和空闲GPU可能抹去收益。将实验假设与实测结果分开，保留回退到原模型的明确路径。",
      "blueprint": {
        "inputs": [
          "量化base与adapter",
          "真实序列batch及硬件",
          "基线和风险切片"
        ],
        "steps": [
          "估峰值显存并试跑",
          "记录训练精度与资源",
          "核关键任务退化",
          "合并或再量化后重测"
        ],
        "outputs": [
          "部署候选与资源实测",
          "精度费用及回退证据"
        ]
      },
      "citations": [
        {
          "url": "https://arxiv.org/abs/2305.14314",
          "label": "QLoRA原始论文",
          "kind": "paper",
          "note": "2023方法论文；硬件与任务结果不直接外推企业训练预算。"
        },
        {
          "url": "https://huggingface.co/docs/peft/main/package_reference/lora",
          "label": "QLoRA与训练显存预算：原始文档",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "learning-lora",
          "type": "complements",
          "reason": "在量化基座上训练adapter。"
        }
      ],
      "en": "Quantized LoRA"
    },
    {
      "id": "domain-legal-authority-verification",
      "title": "法律引证、蕴涵与效力核查",
      "aliases": [
        "引证",
        "蕴涵",
        "citator",
        "效力"
      ],
      "kind": "case",
      "parentId": "domains-legal",
      "order": 6,
      "summary": "把引证存在、支持命题、管辖约束力、时间效力和后续处理分成不同核验层。",
      "question": "真实引用之外，如何核查支持关系、适用法和现行效力？",
      "body": "## 五个不同的核查问题\n法律引证要分别回答：来源是否存在、原文是否支持该主张、适用法域和约束力是否正确、时间上是否有效，以及是否有重要后续处理或反例。链接可打开只回答一小部分；一个真实判例也可能被引用成它从未支持的结论。把这些层分别建字段和结果，避免总分掩盖严重错误。\n\n## 先用确定性检查定位来源\n核案件名称、案号、法院、日期、法条编号、生效失效日、版本和原文片段。合同任务还检查交叉引用、定义、附件、金额、期限和通知计算。每条claim连接evidence_span和source_version，报告绑定产物hash与法律截止日。网页更新、合同改写或数据版本变化后重新验证，不沿用旧passed。\n\n## 蕴涵与适用需要语境\n判断判决中的holding、dicta、事实差异、例外与裁判范围，不能只做关键词命中。语义judge应拿到任务和完整必要证据，输出支持、反对、证据不足或无法判定；专家rubric核关键风险与严重漏项。多个模型一致仍可能共享误解，尤其在复杂法域和事实类比上，不能当成独立法律权威。\n\n## 效力核查需要合格工具\n最新有效性、负面处理、被区分或推翻等，通常需有资格数据库、citator或专业复核。若只有普通网页搜索，系统应明确哪些层已查、哪些未查，不能自动写“该判例仍有效”。官方或商业服务返回结果也要记录查询时间、范围和限制；服务暂不可用时将结论标不确定或进入复核，而非凭模型常识补齐。\n\n## 数据集与错误等级\n按matter、客户、合同模板家族、法院、法律主题和时间划分；同合同原版与红线不能落在训练和test两边。设置伪造判例、错误法域、失效法规和严重风险遗漏的硬阻断，语句清晰不得抵消。分别统计citation existence、entailment、适用法正确、风险召回、合理拒绝和人工审阅时间。\n\n## 使用研究时保留日期\nStanford的法律RAG研究揭示当时特定产品和任务仍会出现幻觉，支持分层验证的必要性，但旧错误率不能直接描述今天所有产品。上线验收应使用选定工具、当前材料与代表性任务。验证报告应清楚列原文、范围、证据和未知，而不是让用户把“有来源”误读为“所有法律命题都已经确认”。",
      "blueprint": {
        "inputs": [
          "法律主张与原文",
          "案号法条版本",
          "法域时点及citator资格"
        ],
        "steps": [
          "核存在与定位",
          "判断蕴涵和适用",
          "查询效力与后续处理",
          "对严重遗漏专业裁决"
        ],
        "outputs": [
          "分层核查报告",
          "未完成效力检查与风险"
        ]
      },
      "citations": [
        {
          "url": "https://law.stanford.edu/wp-content/uploads/2024/05/Legal_RAG_Hallucinations.pdf",
          "label": "Stanford：法律引证与幻觉研究",
          "kind": "paper",
          "note": "原始资料支持方法背景；本页流程与验收为工程建议。"
        }
      ],
      "links": [
        {
          "target": "eval-human-calibration",
          "type": "requires",
          "reason": "法律适用与严重漏项需要专业标准。"
        }
      ],
      "en": "Legal Authority Verification"
    },
    {
      "id": "eval-tool-actions",
      "title": "工具调用与副作用评测",
      "aliases": [
        "工具选择",
        "参数",
        "副作用",
        "幂等"
      ],
      "kind": "concept",
      "parentId": "evaluation-targets",
      "order": 6,
      "summary": "分别验证工具选择、参数语义、权限、分页与外部终态，避免用HTTP成功替代业务成功。",
      "question": "如何判断工具动作正确，并查清超时后的实际结果？",
      "body": "## 分开测会不会选与执行对不对\n工具评测包含选择、参数、执行和效果四层。选择层观察应调用时是否调用、不需要时是否滥用；参数层检查格式和真实语义，例如日期、实体、币种与过滤范围。schema通过不说明用户ID正确，参数都合法也不说明这位调用者有权操作。身份、tenant和权限应由服务端注入并校验。\n\n## 使用真实后置条件\n读工具核对数据属于正确租户、版本和时间范围，包含必要分页，未把空结果当成功答案。写工具核对权威系统终态和操作回执：工单是否存在、金额是否一致、记录版本是否更新。按稳定business_operation_id追踪网络attempt，重试保持同一动作身份。超时意味着结果未知，先查询外部状态，不能假设未执行后再创建一份。\n\n## 对故障和合法路径都宽严适当\n构造参数错误、429、连接中断、审批过期、权限撤销、分页漏页及并发改写。检查工具是否给出可修复错误，Agent是否在预算内恢复、正确停止或升级。不要把参考轨迹作为唯一正确路线；只有法律、账务或依赖合同要求时才强制顺序。两种不同工具组合可以取得同样合法终态。\n\n## 指标支持定位而非只做排名\n报告工具选择precision/recall、参数语义正确率、越权、重复写入、恢复率、调用次数与成本。把工具服务故障和模型误用分开归因，同时保留端到端影响。每次schema或错误格式变化重新跑完整harness；单独mock工具通过无法证明生产连接器、凭据和业务系统正确。最终解释应说清系统确认了什么，以及哪些效果仍缺证据。\n\n## 不只比对标准动作序列\n同一信息可以先按公司再按日期检索，也可以一次组合查询；二者都满足合同，不应因步骤不同判错。相反，参数结构合法但证券身份、单位或收件人错了，必须判语义错误。对结果未知动作，可注入提交后断网，检查系统是否先查询业务状态再决定重试。调用日志、业务记录和回执之间应可关联，不能只依赖模型叙述已经完成。",
      "blueprint": {
        "inputs": [
          "工具及参数合同",
          "动作trace与权限",
          "调用前后权威状态"
        ],
        "steps": [
          "核选择及参数语义",
          "识别重复提交和幂等键",
          "查超时后真实结果",
          "接受多种合法路径"
        ],
        "outputs": [
          "工具错误分类及率",
          "副作用证据与未知项"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc",
          "note": "2026-01-09；官方方法背景，具体合同与阈值须按业务验证。"
        }
      ],
      "links": [
        {
          "target": "eval-deterministic-verifier",
          "type": "requires",
          "reason": "工具结果需要外部状态核查。"
        }
      ],
      "en": "Tool Action Evaluation"
    },
    {
      "id": "learning-dpo",
      "title": "DPO偏好训练",
      "aliases": [
        "DPO",
        "偏好对",
        "chosen rejected"
      ],
      "kind": "concept",
      "parentId": "learning-training",
      "order": 6,
      "summary": "从同任务的可靠偏好对学习取舍，防止标签把自信、篇幅和讨喜误作正确。",
      "question": "怎样保证偏好标签奖励可靠行为，而不是自信文风？",
      "body": "## 偏好对表达一种可学习取舍\nDPO用同一任务下chosen与rejected响应对学习偏好，适合已有可靠比较标签的场景。标签必须说明偏好依据：证据忠实、遗漏更少、提示更合适，还是文风更简练。若评审只喜欢自信与长答案，模型可能更讨喜却更会编造；偏好不自动等于事实正确。\n\n## 样本对要可比较\n两份响应应面对相同输入与证据资格，避免chosen额外拥有rejected看不到的材料。保留任务、来源、评审、分歧、适用日期和错误类型，过滤仅由长度或格式差异决定的无效对。领域专家确认涉及法律效力、财务口径与教学策略的偏好，模型judge提供候选标签时仍需独立校准。\n\n## 不把所有失败都变成负例\n正确拒绝、保留unknown和请求必要信息，有时比完整回答更符合合同。构造安全但过度拒绝、简短但正确、详细却错误的对照，防止优化方向单一。按文档、客户、用户和题型分组划分，去除近重复；训练器、基座、参考策略、tokenizer和模板版本均需记录。\n\n## 上线证据超出偏好胜率\n评测既看pairwise偏好，也看确定性数字、引用、工具、权限和严重错误。模型在训练分布中更受欢迎，不证明未见任务更可靠。对DPO候选和base采用同一完整harness，保留人工修订和成本比较；量化、adapter加载与服务配置变化后重新回归。训练目标与硬授权分别执行，不能把“模型偏好安全”当作访问控制机制。\n\n对chosen与rejected保留完整标注理由，定期抽查标签是否仍符合当前产品合同。",
      "blueprint": {
        "inputs": [
          "同输入的偏好对",
          "领域rubric及理由",
          "base和参考策略"
        ],
        "steps": [
          "核响应对资格可比",
          "过滤长度自信等偏差",
          "分组持出后训练",
          "测偏好事实安全与工具"
        ],
        "outputs": [
          "偏好优化候选",
          "胜率之外的业务回归"
        ]
      },
      "citations": [
        {
          "url": "https://huggingface.co/docs/trl/main/en/dpo_trainer",
          "label": "DPO偏好训练：原始文档",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "eval-human-calibration",
          "type": "requires",
          "reason": "可靠偏好标签是训练输入。"
        }
      ],
      "en": "Direct Preference Optimization"
    },
    {
      "id": "eval-trajectory",
      "title": "执行轨迹、循环与故障归因",
      "aliases": [
        "执行轨迹",
        "循环",
        "故障归因"
      ],
      "kind": "concept",
      "parentId": "evaluation-targets",
      "order": 7,
      "summary": "观察重复调用、预算、遗漏、取消传播与压缩后的约束保留，并用消融实验定位瓶颈。",
      "question": "怎样定位失败来自证据、推理、工具还是控制循环？",
      "body": "## 轨迹帮助解释为什么失败\n最终答案只显示结尾，无法说明Agent是否反复搜索、遗漏要求、使用过期证据或靠超额预算才完成。轨迹评测保存每次模型调用、工具参数与结果、状态变化、任务修订和费用；不需要取得私有思维链。先从可观察事件寻找问题，再决定是否需要更强模型或不同控制逻辑。\n\n## 观察必要约束与进展\n测无信息增益的重复调用、相同候选反复生成、验收项长期不减少、过早宣布完成、缺失tool result、取消后继续执行、压缩后丢失否定条件，以及子Agent重复或冲突。必要顺序由合同规定，例如审批必须先于发送；研究过程不应被固定成唯一脚本。记录关键路径时间，不能仅以更多并发调用判断效率更高。\n\n## 用反事实和消融定位瓶颈\n固定模型、任务和预算，给gold retrieval后若成功恢复，优先修检索；替换正确工具结果后恢复，检查连接器或接口；关掉memory反而变好，检查污染和召回；删去旧prompt补丁后变好，说明harness假设可能已过时。每次只改可解释的一类因素，再用未参与调参的任务检查泛化。\n\n## 将发现转成可修复问题\n失败分类可区分输入歧义、证据缺失、工具接口、计划选择、状态持久化、权限、验证器和基础设施。一个trial可能有主因与次因，保留证据和人工裁决，避免由模型自动写一句根因后直接训练。轨迹评分用于解释和改进，不宜奖励冗长推理或惩罚简短合法路径。能力提升最后仍由业务终态与成本验证。\n\n## 用反事实缩小根因范围\n保持模型和任务不变，先替换正确检索证据，再替换规范工具响应，最后对比有无额外计划步骤。若正确证据立刻消除错误，优先修检索而非训练；若工具返回过长导致关键字段被忽略，则改呈现和上下文预算。轨迹审查关注可见动作和结果，不要求暴露私有思维链。多Agent记录父子任务、共享资源和产物版本，才能找到谁覆盖了谁，以及并行是否真正减少关键路径时间。",
      "blueprint": {
        "inputs": [
          "逐步事件和工具结果",
          "预算停止及取消记录",
          "证据替换对照"
        ],
        "steps": [
          "定位无信息增益循环",
          "区分证据推理及控制故障",
          "用gold retrieval做消融",
          "汇总多Agent冲突及费"
        ],
        "outputs": [
          "根因和修复候选",
          "循环停止及资源报告"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc",
          "note": "2026-01-09；官方方法背景，具体合同与阈值须按业务验证。"
        }
      ],
      "links": [
        {
          "target": "agent-loop",
          "type": "verifies",
          "reason": "验证循环的信息增益、停止、取消与预算行为。"
        },
        {
          "target": "agent-workflow",
          "type": "verifies",
          "reason": "定位固定流程和动态路径的失败点。"
        }
      ],
      "en": "Trajectory Diagnosis"
    },
    {
      "id": "learning-rl-grpo",
      "title": "Agent RL、GRPO与奖励设计",
      "aliases": [
        "RL",
        "GRPO",
        "reward hacking"
      ],
      "kind": "concept",
      "parentId": "learning-training",
      "order": 7,
      "summary": "在可检验任务中优化多步行为，把reward与真实结果的偏差、投机和资源成本纳入验收。",
      "question": "怎样构建可训练环境，并防止策略利用奖励漏洞？",
      "body": "## RL优化奖励，GRPO是一种算法选择\nAgent强化学习围绕策略产生轨迹，再依据reward更新行为；GRPO属于其中一种优化算法，不能与RL当成两个互斥目标。可执行工具环境、算术或受控业务任务能提供较清晰反馈，但奖励仍是业务成功的代理。先定义合法状态、动作、停止、成本与禁止结果，才能讨论训练。\n\n## Reward设计决定优化方向\n奖励可结合任务终态、硬权限、产物验证、工具费用与预算。不要只奖励“测试通过”而允许修改测试，不要只奖励搜索覆盖而鼓励无限调用，也不要只奖励judge喜欢而诱导冗长自信。对关键信息缺失，正确暂停应有明确处理。奖励组件、权重和oracle版本进入训练manifest。\n\n## 多步轨迹增加工程要求\n记录每轮模型输入、工具动作、环境结果、终止原因及资源。状态重放、失败恢复和并行隔离影响训练信号；工具或任务随机性过大时，区分策略质量与环境噪声。模型可利用环境漏洞，必须保护隐藏grader并检查越权、外传与重复副作用。训练环境的可验证性不意味着能无风险连接生产系统。\n\n## 独立验证防止奖励投机\n保留未参与reward调优的任务与攻击变体，使用领域专家和不同验证途径检查泛化。比较基座、SFT基线与RL候选的成功成本、严重错误、稳定性和跨域退化；不要只展示训练reward上升。ART等公开框架提供实现入口，其案例收益不自动外推到企业任务。候选只在资格、持出和受控灰度通过后晋升，不能让训练Agent改写自己的发布规则。",
      "blueprint": {
        "inputs": [
          "隔离环境和动作合同",
          "基线与训练任务",
          "reward及保护oracle"
        ],
        "steps": [
          "采多步轨迹并算奖励",
          "按选定RL算法更新",
          "红队奖励投机和环境洞",
          "独立持出检查泛化"
        ],
        "outputs": [
          "策略候选和训练记录",
          "reward与真实成功差距"
        ]
      },
      "citations": [
        {
          "url": "https://huggingface.co/docs/trl/main/en/grpo_trainer",
          "label": "Agent RL、GRPO与奖励设计：原始文档",
          "kind": "official-doc"
        },
        {
          "url": "https://github.com/OpenPipe/ART",
          "label": "Agent RL、GRPO与奖励设计：原始文档",
          "kind": "code"
        }
      ],
      "links": [
        {
          "target": "eval-deterministic-verifier",
          "type": "requires",
          "reason": "奖励可利用可执行结果，但需防奖励投机。"
        },
        {
          "target": "eval-security-redteam",
          "type": "requires",
          "reason": "检查奖励及验证器漏洞。"
        }
      ],
      "en": "Agent Reinforcement Learning"
    },
    {
      "id": "eval-rag-quality",
      "title": "RAG分段评测与引用质量",
      "aliases": [
        "Recall@k",
        "MRR",
        "nDCG",
        "引证蕴涵"
      ],
      "kind": "concept",
      "parentId": "evaluation-targets",
      "order": 8,
      "summary": "拆开测解析、召回、排序、上下文与回答，标注真正包含答案的证据片段。",
      "question": "检索命中与答案可信分别要怎样测？",
      "body": "## 对检索链逐段定位\nRAG表现由接入、解析、切块、召回、排序、上下文组装、生成和引用共同决定。先用人工标注的answer-bearing passages判断证据是否进入候选，再判断reranker和context builder是否保留，最后检查回答是否忠实使用。若正确段落根本没被解析出来，换生成模型通常不是第一解法。\n\n## 指标测不同能力\nRecall@k看必要证据是否被召回，MRR或nDCG看排序；证据覆盖看多项要求是否都有依据；引用精确率和蕴涵看来源是否真正支持结论。还要测无答案检出、冲突呈现、陈旧源使用和拒答。单纯“相关文档命中”不足以证明包含答案，关键词匹配也不能证明引证有效。\n\n## 构造企业真实难例\n覆盖中英混合、内部简称、同名公司、扫描表格、跨文档合并、例外与否定、版本冲突、删除来源、新制度生效日和无权限的正确答案。对后者，即使答案内容正确，只要引用或上下文泄漏其他部门资料，也应判安全失败。离线数据资格要与查询者一致，不能用管理员召回率代表普通员工体验。\n\n## 评测必须跟随版本与权限\n固定语料快照、索引generation、embedding、reranker、query改写和预算，同时保留实际ACL决策。更新源、撤销权限或更换chunk策略后，既跑检索层，也跑完整任务回归。用更大的k可能提高召回，却增加成本、噪声和暴露面；应比较端到端成功而非追求单指标最高。本页只规定如何测质量，检索与存储实现由知识分支承载。\n\n## 建立可审阅的证据对照\n每题保留必须找到的证据、可替代来源、无答案条件以及用户可见范围。分别评估只需一个段落和需要跨文件拼接的问题，避免高召回只来自短单跳题。引用定位正确后，还要核它支持的是原始事实还是模型新增推论；表格中的单位、期间与脚注都可能改变命题。替换过期文件或撤回权限后重跑同题，检查索引、缓存和最终引用是否同步变化。",
      "blueprint": {
        "inputs": [
          "标准证据问题集",
          "候选检索和生成引用",
          "文档版本及ACL"
        ],
        "steps": [
          "测召回排序与过滤",
          "核证据覆盖和引用定位",
          "评支持矛盾及无答案",
          "测撤权删除及陈旧源"
        ],
        "outputs": [
          "分段质量及引用证据",
          "召回或生成根因定位"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc",
          "note": "2026-01-09；官方方法背景，具体合同与阈值须按业务验证。"
        }
      ],
      "links": [
        {
          "target": "eval-llm-judge",
          "type": "complements",
          "reason": "语义Judge是可选评分方式；也可使用专家标注与确定性验证，不把它作为所有任务的必要条件。"
        }
      ],
      "en": "RAG Evaluation"
    },
    {
      "id": "learning-distillation",
      "title": "蒸馏与拒绝采样",
      "aliases": [
        "蒸馏",
        "教师学生",
        "拒绝采样"
      ],
      "kind": "concept",
      "parentId": "learning-training",
      "order": 8,
      "summary": "用教师产生候选并独立筛选，同时检查教师正确性、数据训练权和迁移后的净收益。",
      "question": "怎样将教师能力转移给学生，又不放大教师错误？",
      "body": "## 教师生成、筛选和训练是三件事\n蒸馏可以使用强模型的输出或行为作为学生学习材料；rejection sampling则生成多个候选并筛去不合格结果，筛选本身并未改变权重。两者可以结合，但应分别记录生成预算、筛选标准、训练目标和最终部署。教师更强不意味着每个答案都正确，也不意味着学生能无损复制能力。\n\n## 独立验证比自称成功可靠\n对数字用程序复算，对引用查原文与蕴涵，对工具动作查终态，对开放解释用经校准的rubric和专家抽审。不要仅保留教师自评最高的轨迹，否则同源错误会进入训练。保留正确拒绝、unknown、异常恢复和反例，避免数据只覆盖顺利完成路径。筛选器版本、证据和被拒原因同样是资产。\n\n## 核对数据与模型使用权\n分别检查教师服务条款、输出训练用途、客户材料授权、基座许可证和最终分发方式。可通过API生成内容不自动代表可用于竞争模型训练，能读取私人文档也不自动具备训练权。对敏感内容执行用途控制、去标识与保留策略，训练数据和评测数据分组隔离，防合成改写污染持出集。\n\n## 用学生在真实任务上的表现结账\n比较教师、未训练学生和训练学生在相同harness、工具和预算下的正确性、拒答、费用与P95。生成和筛选的前期成本要用于项目可行性判断，部署晋升则看未来增量价值。若学生需要更多重试或专家修订，token单价更低也可能更贵。保留跨域和安全回归，不以某个模仿分数代替领域能力。\n\n筛选通过率、人工裁决和被拒样本分布也应保存，以便识别教师或验证器的共同盲点。",
      "blueprint": {
        "inputs": [
          "教师及输出使用资格",
          "授权任务和学生基座",
          "独立验证及持出"
        ],
        "steps": [
          "生成目标或教师反馈",
          "核事实工具及拒绝",
          "按蒸馏目标训练学生",
          "比成本和任务退化"
        ],
        "outputs": [
          "学生与数据manifest",
          "错误传播及泛化报告"
        ]
      },
      "citations": [
        {
          "url": "https://huggingface.co/docs/trl/en/distillation_trainer",
          "label": "TRL：Distillation Trainer",
          "kind": "official-doc",
          "note": "官方实现涵盖on-policy知识蒸馏；具体目标和数据资格需按方案核对。"
        },
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent评测方法",
          "kind": "official-doc",
          "note": "学习收益需在独立业务任务验证。"
        }
      ],
      "links": [
        {
          "target": "learning-data-contract",
          "type": "requires",
          "reason": "教师输出和训练用途分别核资格。"
        },
        {
          "target": "eval-human-calibration",
          "type": "requires",
          "reason": "教师自称成功不能独立判定正确。"
        }
      ],
      "en": "Knowledge Distillation"
    },
    {
      "id": "eval-memory-lifecycle",
      "title": "记忆写入、使用与遗忘评测",
      "aliases": [
        "记忆评测",
        "遗忘",
        "污染"
      ],
      "kind": "concept",
      "parentId": "evaluation-targets",
      "order": 9,
      "summary": "以多session脚本检验偏好写入、纠正、恢复、删除和撤权，再比较不同记忆策略的净收益。",
      "question": "记住、找回、正确使用和按要求删除，如何分别验证？",
      "body": "## 记得更多不一定做得更好\nmemory评测应分别测写入、检索、应用和删除。写入正确但召回不到没有价值；召回正确但用错场景会损害结果；反复召回旧错误可能让系统越来越固执。先定义信息的主体、scope、来源、有效期和可撤回方式，再决定哪些跨session行为应该保持。\n\n## 用有顺序的多Session脚本\n一组case可以先表达偏好，下一session检查应用，再纠正偏好、切换任务、恢复历史、删除条目并再次询问。加入临时要求、推断信息、来源冲突、敏感内容、其他用户的相似记录和撤权。确认更正能覆盖旧事实，临时任务规则不被永久化，模型不会以“记忆”作为越权披露理由。\n\n## 比较净收益与副作用\n在统一模型、任务和预算下比较no-memory、完整历史、摘要memory和审查后memory。指标包含任务提升、召回精确率、错误延续、token和检索费用、用户修正成本及隐私失败。不能仅凭更多命中或更长记录宣称学习成功。数据切分以用户或组织为单位，避免相邻session落在训练与测试两边。\n\n## 保留被测状态，隔离其他污染\n每次trial恢复case声明的初始memory；长期积累case需要保留明确预置的前史，不能一律清空。版本更新后检查旧memory格式与来源权限是否兼容，回滚代码也要处理新版本已经写入的条目。删除验收包含索引、缓存、摘要和后续召回，不只界面隐藏。产品应展示可检查的记忆依据，而不是要求用户相信一句“我已经忘记”。\n\n## 用时间线而非单轮题测记忆\n构造学生最初答错、后来纠正、教师覆盖判断、最后请求删除的多次会话。每步预先指定应记、可暂存、禁止跨用户使用以及应遗忘的内容，检查后续行为是否随版本变化。既看重要事实漏记，也看无关旧记忆误导当前任务的频率。删除后不能只查主表，还应测检索索引、摘要、缓存及派生状态的实际可见性。若无法精确清除某类产物，应把该限制写进产品合同。\n\n## 从端到端分数拆解故障\n[EvalMem](https://arxiv.org/abs/2609.22231)把诊断分为事实是否被写入、原生检索是否返回可用证据、模型在oracle证据下能否回答。工程上可对应建立三组对照，避免把编码遗漏误诊为需要更大模型。其结果来自所测系统与数据集，不是所有企业记忆的普遍故障比例。\n\n[LongMemEval-V2](https://arxiv.org/abs/2605.12493)把环境状态、动态变化、工作流和常见陷阱等经验纳入评测；截至研究日为Work in Progress。企业可借鉴环境经验的测试维度，再用自有任务验证准确率与延迟，不直接采用论文分数作上线保证。",
      "blueprint": {
        "inputs": [
          "多session任务序列",
          "候选记忆与scope",
          "写入检索删除规则"
        ],
        "steps": [
          "核事实和偏好写入资格",
          "对照无记忆及整理记忆",
          "检查应用和冲突",
          "验证跨用户隔离与遗忘"
        ],
        "outputs": [
          "记忆净收益和污染率",
          "纠正删除的生效证据"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc",
          "note": "2026-01-09；官方方法背景，具体合同与阈值须按业务验证。"
        },
        {
          "url": "https://arxiv.org/abs/2609.22231",
          "label": "EvalMem：操作层记忆诊断",
          "kind": "paper",
          "note": "编码、检索和oracle生成分层；论文实验不等于企业生产验证。"
        },
        {
          "url": "https://arxiv.org/abs/2605.12493",
          "label": "LongMemEval-V2：环境经验记忆评测",
          "kind": "paper",
          "note": "截至2026-10-15标为Work in Progress；关注经验维度与准确率/延迟权衡。"
        }
      ],
      "links": [
        {
          "target": "agent-session",
          "type": "verifies",
          "reason": "用多session序列检查记忆是否正确带入和隔离。"
        }
      ],
      "en": "Memory Evaluation"
    },
    {
      "id": "learning-training-release",
      "title": "训练实验、Checkpoint与推理发布",
      "aliases": [
        "训练发布",
        "模型manifest",
        "遗忘"
      ],
      "kind": "concept",
      "parentId": "learning-data",
      "order": 9,
      "summary": "冻结基座、数据和模板做公平对照，发布包含adapter与serving参数的完整模型版本。",
      "question": "微调、合并和量化后，怎样取得完整Agent发布资格？",
      "body": "## 训练实验需要可重建的合同\n冻结基座revision、tokenizer、chat template、数据manifest、训练目标、adapter配置、代码依赖与资源；记录序列长度、batch、学习率、epoch、seed、精度、硬件、时间、费用及恢复情况。先比较base加原prompt、base加改进prompt、训练候选加同一prompt，避免把提示改善误记成权重收益。\n\n## 看拟合之外的表现\n学习曲线与验证loss能帮助发现过拟合，但不能证明工具正确、引证有效或学生真的学会。完整harness上测未见任务、严重错误、格式、拒答、校准、跨域能力、人工修订和有效成本。训练数据中的成功方法需在新实体、新文档和异常条件下仍然适用，才有迁移意义。\n\n## 模型发布包含多个依赖\n发布对象不仅是checkpoint，还包括基座、adapter、tokenizer、模板、工具协议、serving版本、精度和推理参数。合并adapter、重新量化、更换kernel或batch策略后做代表性回归，确认关键数值和安全切片未退化。多租户端点核adapter路由与KV隔离，模型ID相同不能覆盖这些差异。\n\n## 容量与退出路径一起测\n评估GPU空闲、自动扩缩容、冷启动、吞吐、出站和平台费用；高利用率可能适合专用端点，小流量API可能更易维护。保存可导出checkpoint、adapter、数据与日志，核平台格式与许可。新模型先在离线、shadow和canary取得资格，再切换受信发布指针；若回退还涉及新写memory和业务状态，应有独立处置方案，而非只恢复旧权重。",
      "blueprint": {
        "inputs": [
          "base adapter数据manifest",
          "模板量化及serving",
          "基线和独立test"
        ],
        "steps": [
          "核训练部署可追溯性",
          "比prompt训练模型候选",
          "测遗忘成本及完整产品",
          "冻结组合受控灰度"
        ],
        "outputs": [
          "正式训练产物组合",
          "资格依赖及回滚路径"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent评测方法",
          "kind": "official-doc",
          "note": "学习收益需在独立业务任务验证。"
        }
      ],
      "links": [
        {
          "target": "eval-model-migration",
          "type": "requires",
          "reason": "微调和量化模型也需完整升级评测。"
        },
        {
          "target": "eval-release-rollback",
          "type": "requires",
          "reason": "adapter、模板和serving配置共同发布。"
        },
        {
          "target": "release-manifest",
          "type": "requires",
          "reason": "训练产物必须与模板、工具及serving组合绑定。"
        }
      ],
      "en": "Training Release"
    },
    {
      "id": "agent-definition-version",
      "title": "Agent定义与版本",
      "en": "Agent Definition Version",
      "aliases": [
        "Agent Registry",
        "能力定义"
      ],
      "kind": "concept",
      "parentId": "runtime-task-session",
      "order": 10,
      "summary": "描述Agent能力、prompt、工具和策略的不可变配置。",
      "question": "怎样发布和回滚能力配置，同时解释历史结果？",
      "body": "描述Agent能力、prompt、工具和策略的不可变配置。\n\nAgent定义是一份能力配置，运行实例是它的一次使用。定义可以包含prompt模块、模型路由、工具schema、停止策略和适用领域；部署则把获准版本发布到某个环境或租户。把二者分开，才能在同一时间服务旧任务、新任务和灰度实验，而不靠一个可变名称解释结果。\n\n版本不仅是一个字符串。应保存定义正文与依赖hash、owner、变更理由、评测报告、批准状态和回滚目标。工具接口、检索配置或memory政策变化也可能改变能力，即使prompt没改。公开框架提供不同程度的配置和注册能力，企业仍需定义自己的发布合同，不能默认框架替你冻结了全部依赖。\n\n已有Run绑定开始时的配置快照；需要中途变更时记录明确边界和原因。紧急安全策略可以立即缩减能力，但应使相关Run重新核验，不能把旧批准当长期通行证。模型厂商未提供固定snapshot时，要记录可复现性的限制，并持续运行哨兵任务。\n\n金融与法律Agent可以共享一个基类，却使用不同领域规则和工具范围。不要把所有变化塞进全局system prompt，再同时影响教育与投研。验证应能从任一产物找回对应Agent定义、模型与工具版本，并比较灰度和基线。配置回滚也要检查数据schema和已发生副作用；把指针改回旧版本，不能撤回已经发出的消息。\n\n定义还可以声明适用任务和停止边界。例如某版本只支持公开财报比较，不支持交易执行；新增下单工具时，不是普通文案更新，而是能力合同变化。即使配置文件只有几行差异，也要重新评测授权、回执和失败处理。版本号的大小不能代替对行为变化的判断。\n\n版本目录还应允许停用存在缺陷的能力，并说明对新任务和在途任务分别怎样生效。\n\n**实践重点**：部署指向获准版本；执行记录精确配置与工具schema，不靠名字识别。\n\n**验证抓手**：重放旧任务时能定位对应定义和依赖版本。\n\n**常见误区**：运行中静默修改所有Agent的规则，导致结果无法归因。\n\n[OpenAI：Agent运行时选择](https://developers.openai.com/api/docs/guides/agents)；[OpenCode：session_v2与消息表源码](https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/sql.ts#L22-L144)。",
      "blueprint": {
        "inputs": [
          "能力配置及依赖",
          "评测与批准结果",
          "目标租户和环境"
        ],
        "steps": [
          "生成不可变定义版本",
          "绑定依赖hash",
          "发布部署指针",
          "保留灰度与回滚记录"
        ],
        "outputs": [
          "AgentDefinition版本",
          "AgentDeployment",
          "可追溯Run配置"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/agents",
          "label": "OpenAI：Agent运行时选择",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/sql.ts#L22-L144",
          "label": "OpenCode：session_v2与消息表源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        }
      ],
      "links": []
    },
    {
      "id": "agent-engineering-layers",
      "title": "Model、Framework、Runtime 与 Harness",
      "parentId": "foundations",
      "kind": "concept",
      "order": 10,
      "en": "Agent engineering layers",
      "aliases": [
        "框架",
        "SDK",
        "Runtime"
      ],
      "summary": "把生成、开发抽象、真实执行与业务责任分开。",
      "question": "为什么换一个模型或 SDK，产品仍可能失败？",
      "body": "## 四种不同的能力\nModel 根据上下文生成文本或工具请求，它并不天然拥有数据库连接、持久状态或授权。Framework／SDK 提供工具定义、状态图、handoff、适配与 tracing 等开发抽象。Runtime 实际负责排队、资源、恢复和执行。Harness 包围模型，负责组装上下文、调用工具、处理反馈与停止；loop 是其中不断观察和行动的核心。\n\n这些是职责划分，并非必须购买四套产品。托管平台可能同时提供 runtime 和 harness；框架也可能逐步扩展到持久执行。采购时要把功能映射回责任，而不是只根据产品名称归类。OpenAI 的架构文档明确分出应用服务器、harness 与环境；Anthropic 的 Managed Agents 说明也区分会话、harness 和 sandbox。这说明相同“Agent”一词可能覆盖不同控制边界。\n\n## 如何验证边界\n把模型服务临时替换成只返回固定工具请求的桩，检查工具授权、状态保存、取消与最终完成是否仍由程序保证；再使 worker 中断，检查恢复是否依赖只存在内存里的状态。如果业务规则随模型口头承诺而变化，说明控制逻辑还没有落到系统。\n\n## 选型启示\n在概念验证阶段，可以使用一个进程和现成 SDK。进入多用户、长任务和外部写入后，必须知道谁负责会话事实、恢复权威和工具副作用。产品路线页按这些维度比较，而不是按框架功能列表简单计数。",
      "blueprint": {
        "inputs": [
          "模型输出",
          "工具合同"
        ],
        "steps": [
          "识别开发抽象",
          "定位执行权威",
          "核对完成责任"
        ],
        "outputs": [
          "组件职责图",
          "可替换边界"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/agents-api/architecture",
          "label": "OpenAI：Agents API architecture",
          "kind": "official-doc"
        },
        {
          "url": "https://www.anthropic.com/engineering/managed-agents",
          "label": "Anthropic：Managed Agents 架构",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "agent-harness",
          "type": "complements",
          "reason": "本页解释层次，Harness页展开执行机制。"
        },
        {
          "target": "products",
          "type": "feeds",
          "reason": "按责任边界比较具体产品。"
        }
      ]
    },
    {
      "id": "agent-harness",
      "title": "Agent Harness",
      "en": "Agent Harness",
      "aliases": [
        "执行外围层"
      ],
      "kind": "concept",
      "parentId": "runtime-harness",
      "order": 10,
      "summary": "把模型、工具、上下文与恢复边界组合成可执行系统的外围层。",
      "question": "模型之外，哪些执行与控制能力值得复用，哪些应由企业掌握？",
      "body": "把模型、工具、上下文与恢复边界组合成可执行系统的外围层。\n\n模型产生的是下一段内容或行动请求，harness把这些请求放进一个有边界的工作系统。同一个模型接上不同的工具、历史管理、停止条件和恢复机制，会呈现不同的Agent能力。企业选型因此应问“这层替我承担哪些责任”，而不是只问能否调用某个模型。金融研究需要可复算产物，合同研究需要来源与法域，教学需要区分提示和独立作答；这些领域合同不应藏在通用循环里。\n\n公开的Claude Code文档把harness解释为提供工具、管理模型上下文的外围层。OpenAI托管架构进一步区分harness、environment与application server。两者支持一个重要拆分：推理进程可以重启，计算环境可以重建，业务Task与证据仍须有权威记录。不要因为某个沙箱有文件，就将它当数据库；也不要因为模型服务保存了conversation，就认为外部业务动作能够安全恢复。\n\n设计上至少列出三张责任表：谁决定下一步，谁有权执行，谁证明完成。主Agent负责探索与综合；工具网关持有真实授权；验证器检查业务后置条件。编排可以是同一服务内的模块，不要求一开始拆出微服务。接口应允许替换运行时，同时保留Task、ToolOperation、Artifact和Evidence的稳定身份。\n\n选择托管harness能减少沙箱、流处理和压缩的维护，但会增加对供应商会话格式、配额、区域和生命周期的依赖。选择SDK可掌握部署和数据，却要自己处理租约、取消、恢复和运维。评估两条路线应使用同一业务范围与失败场景；只跑通问答或安装示例不能证明企业适用。\n\n一个可实施的起点是保留企业自己的Task与证据服务，把托管harness接成RuntimeAdapter。输入是一份范围明确的研究任务，输出是结构化产物、工具回执和轨迹引用。若未来更换供应商，业务记录仍能读取，测试集仍能重跑，而不是只能看到某个已停用会话的ID。这个退出能力应在试用时验证，不必等到采购合同结束。\n\n**实践重点**：区分业务控制、模型推理、执行环境与持久状态；以适配器接入托管或自运维运行时。\n\n**验证抓手**：用真实工具、权限和重启场景验证整条任务链。\n\n**常见误区**：把模型API当完整Agent，或把coding harness直接当企业平台。\n\n[Claude Code：工作原理](https://code.claude.com/docs/en/how-claude-code-works)；[OpenAI：托管Agents架构](https://developers.openai.com/api/docs/guides/agents-api/architecture)。",
      "blueprint": {
        "inputs": [
          "业务任务合同",
          "可用模型与工具",
          "身份和部署约束"
        ],
        "steps": [
          "分开决策、执行与验证责任",
          "选择托管或应用内runtime",
          "建立可导出的业务状态",
          "在真实失败边界验证"
        ],
        "outputs": [
          "运行责任图",
          "Runtime适配合同",
          "采用与退出条件"
        ]
      },
      "citations": [
        {
          "url": "https://code.claude.com/docs/en/how-claude-code-works",
          "label": "Claude Code：工作原理",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://developers.openai.com/api/docs/guides/agents-api/architecture",
          "label": "OpenAI：托管Agents架构",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": []
    },
    {
      "id": "build-buy-boundary",
      "title": "自建、复用与托管边界",
      "parentId": "foundations",
      "kind": "concept",
      "order": 10,
      "en": null,
      "aliases": [
        "框架选型",
        "采购",
        "TCO"
      ],
      "summary": "围绕状态所有权、退出路径与总成本选择技术路线。",
      "question": "什么应该自己掌握，什么可以交给供应商？",
      "body": "## 从控制权开始比较\n框架通常把灵活性留给开发者，也把恢复、部署、安全和升级负担留给团队；托管harness可交付现成沙箱与执行能力，但可能限制模型、环境、状态导出和生命周期。二者不存在统一优胜者，要按任务和控制要求比较。\n\n企业适合掌握稳定的领域工具接口、权限语义、知识原件与版本、任务成功条件和评测数据。框架私有类型可以停留在适配层，避免业务数据只存在供应商的会话对象里。评估时要求能导出会话事件、产物、来源与运行版本，并说明重放和迁移的限制。\n\n## 总成本包含什么\n除模型token费，还要计入工程维护、失败重试、人工复核、数据清理、观测平台、沙箱、供应商限流与迁移成本。开源许可证需要核对具体版本与组件，公开代码不代表服务免费，事故泄漏更不构成使用许可。\n\n## 采购实验\n用同一组任务和初始状态，跑最简模型调用、一个开源框架和一个托管方案。比较完成率、严重错误、p95、每个验收结果成本、恢复与导出。在目标租户下验证权限撤回、回调重投、取消和计费，公开文档只能证明声明而不能证明你的集成效果。产品比较页因此同时列执行边界、模型边界、持久状态、可用性和限制，避免用演示视频替代验收。",
      "blueprint": {
        "inputs": [
          "业务合同",
          "团队与成本约束"
        ],
        "steps": [
          "对齐控制边界",
          "同任务运行候选",
          "验证迁移与总成本"
        ],
        "outputs": [
          "复用决定",
          "采购验收清单"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/agents-api/architecture",
          "label": "OpenAI：Agents API architecture",
          "kind": "official-doc"
        },
        {
          "url": "https://www.anthropic.com/engineering/managed-agents",
          "label": "Anthropic：Managed Agents 架构",
          "kind": "official-doc"
        },
        {
          "url": "https://www.anthropic.com/engineering/building-effective-agents",
          "label": "Anthropic：Building effective agents",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "products",
          "type": "feeds",
          "reason": "具体产品路线按同一边界比较。"
        },
        {
          "target": "effective-result-cost",
          "type": "requires",
          "reason": "成本按验收结果而非单token计量。"
        }
      ]
    },
    {
      "id": "child-agent-contract",
      "title": "子Agent委派合同",
      "en": "Subagent Contract",
      "aliases": [
        "委派",
        "子任务Agent"
      ],
      "kind": "concept",
      "parentId": "runtime-delegation",
      "order": 10,
      "summary": "规定子任务输入、权限子集、预算和结构化产物。",
      "question": "怎样委派局部工作而不扩权、不丢证据？",
      "body": "规定子任务输入、权限子集、预算和结构化产物。\n\n子Agent适合处理可独立定义、可检查并能合并的局部任务。委派合同应包含目标、输入快照、允许来源、权限子集、预算、deadline、预期产物与验证方式。仅给一个角色名如“法律专家”，不能保证它拥有正确资料，更不能保证结果可靠。\n\n上下文应按任务需要选择。Claude Agent SDK提供子Agent能力，dots使用文档也区分持续协调者与获得必要上下文的委派任务。这些公开产品合同值得借鉴，但不意味着企业应默认复制用户全部聊天和memory。子Agent只需比较某份合同条款，就不应自动看到其他客户matter。\n\n能力委派不能扩权。父Agent获得的凭证和批准上限是子任务的上限，子Agent可进一步缩减scope。需要新资源时回到控制平面，不以“另找一个Agent”绕过拒绝。子任务的工具轨迹、引用和费用仍归入可审计记录，返回给父Agent的是结构化产物和证据指针，而非无法定位的一段总结。\n\n取消、失败与超时都要有明确传播规则。父Task取消通常应阻止依附子任务的新动作；已经独立获准的后台工作是否继续，需要产品合同决定。合并前先检查子结果是否通过局部验收。测试跨租户输入、过宽memory召回、失联子任务和恶意返回指令，避免把委派结果当高优先级规则。\n\n适合委派的例子是让一个子Agent检查三条引用原文，另一个复算一组指标；二者有小范围输入和明确输出。若把“把整个报告做完”重复交给五个Agent，通常只是复制成本。开始并行前先问结果是否能独立验收，父Agent是否有能力识别错误与冲突。\n\n子Agent数量应由可分解工作和配额决定。对强共享状态的连续编辑，单一owner通常更容易得到可解释结果，增加角色未必提高质量。\n\n**实践重点**：限制scope与截止时间；子Agent工具轨迹保留，父Agent接收证据产物。\n\n**验证抓手**：验证权限不能放大、取消传递与子产物复核。\n\n**常见误区**：默认继承全部凭证与memory，或只返回无来源结论。\n\n[Claude Agent SDK：概览](https://code.claude.com/docs/en/agent-sdk/overview)；[OpenAI dots：Tasks and memory](https://learn.chatgpt.com/docs/dots/tasks-and-memory)。",
      "blueprint": {
        "inputs": [
          "局部目标与输入快照",
          "父级权限和预算上限",
          "产物schema与verifier"
        ],
        "steps": [
          "收缩任务scope",
          "启动独立上下文",
          "保存子轨迹与产物",
          "复核后返回父任务"
        ],
        "outputs": [
          "结构化子产物",
          "来源与局部验证",
          "费用和取消状态"
        ]
      },
      "citations": [
        {
          "url": "https://code.claude.com/docs/en/agent-sdk/overview",
          "label": "Claude Agent SDK：概览",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://learn.chatgpt.com/docs/dots/tasks-and-memory",
          "label": "OpenAI dots：Tasks and memory",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": [
        {
          "target": "business-task",
          "type": "requires",
          "reason": "本节点的设计需要先明确业务Task。"
        },
        {
          "target": "tool-authorization",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具授权网关。"
        }
      ]
    },
    {
      "id": "claude-code",
      "title": "Claude Code",
      "en": "Claude Code",
      "aliases": [
        "Claude Agent SDK",
        "Claude Code SDK"
      ],
      "kind": "product",
      "parentId": "products-harness",
      "order": 10,
      "summary": "面向代码、文件和工具任务的Agent产品。",
      "question": "它怎样运行Agent，哪些状态和权限仍由应用负责？",
      "body": "观察时点：2026-10-15。面向代码、文件和工具任务的Agent产品。\n\n## 已公开的技术路线与控制边界\n\nClaude模型＋工具循环＋context管理；可通过Agent SDK把同类能力嵌入应用。CLI或SDK进程执行工具；应用负责业务权限和任务状态；官方产品源码不因公开repo而变成宽松开源。\n\n理解Claude Code，首先要把模型与产品外围分开。模型负责理解与推理，产品提供文件、搜索、shell、网络和扩展能力，并管理context、会话、权限及恢复入口。官方把任务描述为收集上下文、行动、验证再循环，实际阶段可能交织，而不是一次规划后顺序跑完。\n\n对企业最有参考价值的是完整任务体验：用户可以在运行时纠正方向，工具结果进入后续判断，长对话需要压缩，完成前应检查产物。项目指令和自动记忆帮助跨会话连续，但官方明确它们属于context，不能作为无条件强制配置。要阻止某类动作，仍需执行前hook、权限规则或外层工具网关。\n\n会话与环境也要分开。文档描述本地JSONL历史支持resume和fork；同一历史可以在新模型窗口继续。文件checkpoint主要用于本地文件变化，不能撤销远端API、数据库或已经发送的消息。企业若把它接入正式业务，应额外保存Task、业务操作ID、批准参数与外部回执。\n\nClaude Agent SDK让应用在自己运维的进程中使用Claude Code的工具循环与context管理；托管Managed Agents则是另一条部署路线。二者不等于直接模型Client SDK，也不等于可fork的宽松开源harness。选型时应比较运行控制、状态导出、数据保留和实际产品条款，不能用可下载binary替代许可判断。\n\n适合的采用方式，是把它作为代码、文件处理或受限执行worker，通过自有控制平面提交明确任务，接收产物与轨迹。企业身份、金融口径、法律证据和教学验收留在通用服务中，避免所有业务状态被某一种session格式锁住。模型替换也要分别验证native能力、工具与压缩状态，不能只换一个兼容端点。\n\n试用不应止于让它改一个文件。要检查中断后的工具状态、跨会话继续、权限缩减、来源撤回、文件导出和真实产物验证。官方文档能够支撑上述可见机制，但不能证明某企业账号已获全部功能，也不能证明同样流程在三个领域达到所需成功率。\n\n一个适合的首个场景是让它处理一组获准PDF和表格，生成可编辑报告及复算脚本。外层系统先提供资料清单和截止日，只挂载必要文件；运行完成后检查引用定位、脚本计算和导出格式，再让业务owner决定发布。这个边界充分使用文件与代码能力，也避免让Agent自行寻找生产凭证。若后续要批量发送或更新正式记录，应走独立业务工具与批准流程，不能因为同一会话已能执行shell就扩大动作范围。\n\n## 数据、记忆与模型替换\n\n公开文档描述本地JSONL session、resume/fork、项目指令、auto memory与compaction。\n\n以Claude原生能力为核心；不能把其他模型API兼容等同完整harness可替换。\n\n## 执行、部署与采用取舍\n\n本地或选定环境中的Claude Code进程；SDK由应用运维。模型驱动工具循环，扩展skills、hooks、MCP与子Agent。CLI、IDE、桌面与SDK部署路径分别核验；托管服务另列。\n\n成熟的文件工具与上下文体验可减少自写harness工作；仍需企业控制和领域验证。\n\n观察于2026-10-15：按平台、套餐和版本核实；本页未证明特定账号可用。\n\n许可边界：Anthropic商业条款；组件依各自许可。采用前按实际使用方式核验组件、云服务与模型条款。\n\n## 证据范围与未知\n\n官方工作原理、权限、记忆和Agent SDK文档可核；不使用意外暴露源码推断当前实现。\n\n未公开或仍需目标环境验证的部分：企业三域任务效果；所有平台权限与保留矩阵；完整内部harness源码。本页不以产品表面行为推断其隐藏实现。\n\n[Claude Code：工作原理](https://code.claude.com/docs/en/how-claude-code-works)；[Claude Code：权限配置](https://code.claude.com/docs/en/permissions)；[Claude Code：指令与记忆](https://code.claude.com/docs/en/memory)；[Claude Code：Prompt caching](https://code.claude.com/docs/en/prompt-caching)；[Claude Agent SDK：概览](https://code.claude.com/docs/en/agent-sdk/overview)。",
      "blueprint": {
        "inputs": [
          "明确的代码或文件Task",
          "受限工作目录与工具",
          "企业验收及权限"
        ],
        "steps": [
          "创建受控执行环境",
          "提交任务并允许用户steer",
          "收集工具与文件产物",
          "外层验证并保存业务状态"
        ],
        "outputs": [
          "文件或代码产物",
          "执行和权限记录",
          "业务验证结果"
        ]
      },
      "citations": [
        {
          "url": "https://code.claude.com/docs/en/how-claude-code-works",
          "label": "Claude Code：工作原理",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://code.claude.com/docs/en/permissions",
          "label": "Claude Code：权限配置",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://code.claude.com/docs/en/memory",
          "label": "Claude Code：指令与记忆",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://code.claude.com/docs/en/prompt-caching",
          "label": "Claude Code：Prompt caching",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://code.claude.com/docs/en/agent-sdk/overview",
          "label": "Claude Agent SDK：概览",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": [
        {
          "target": "agent-harness",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent Harness的具体产品路线。"
        },
        {
          "target": "agent-loop",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent执行循环的具体产品路线。"
        },
        {
          "target": "agent-session",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent Session的具体产品路线。"
        },
        {
          "target": "context-compaction",
          "type": "implements",
          "reason": "公开能力或可见源码体现上下文压缩的具体产品路线。"
        },
        {
          "target": "human-approval",
          "type": "implements",
          "reason": "公开能力或可见源码体现人工审批合同的具体产品路线。"
        },
        {
          "target": "prefix-kv-cache",
          "type": "implements",
          "reason": "公开能力或可见源码体现Prompt与KV前缀缓存的具体产品路线。"
        }
      ],
      "productRoute": {
        "vendor": "Anthropic",
        "category": "代码与文件Harness",
        "execution": "本地或选定环境中的Claude Code进程；SDK由应用运维。",
        "orchestration": "模型驱动工具循环，扩展skills、hooks、MCP与子Agent。",
        "context": "项目指令、auto memory、会话历史、skills与工具结果共同进入context，并有压缩机制。",
        "persistence": "公开文档描述本地JSONL session、resume/fork、项目指令、auto memory与compaction。",
        "modelBoundary": "以Claude原生能力为核心；不能把其他模型API兼容等同完整harness可替换。",
        "deployment": "CLI、IDE、桌面与SDK部署路径分别核验；托管服务另列。",
        "license": "Anthropic商业条款；组件依各自许可",
        "availability": "观察于2026-10-15：按平台、套餐和版本核实；本页未证明特定账号可用。",
        "strengths": "成熟的文件工具与上下文体验可减少自写harness工作；仍需企业控制和领域验证。",
        "limits": "待验证或未公开：企业三域任务效果；所有平台权限与保留矩阵；完整内部harness源码。公开能力不等同企业负载与领域任务实测。"
      }
    },
    {
      "id": "claude-managed-agents",
      "title": "Claude Managed Agents",
      "en": "Claude Managed Agents",
      "aliases": [
        "Managed Agents"
      ],
      "kind": "product",
      "parentId": "products-platforms",
      "order": 10,
      "summary": "由Anthropic托管harness和session基础设施的Agent服务。",
      "question": "它怎样运行Agent，哪些状态和权限仍由应用负责？",
      "body": "观察时点：2026-10-15。由Anthropic托管harness和session基础设施的Agent服务。\n\n## 已公开的技术路线与控制边界\n\n持久session日志、harness与sandbox解耦；通过API配置和执行。Anthropic负责托管runtime；应用保留业务合同、外部工具权限、证据和验收。\n\n托管Agent服务改变的是基础设施责任，而不是业务责任。Managed Agents由Anthropic运行harness，通过API配置session和工具环境；应用仍决定用户能做什么、哪些资料可发出，以及何时算任务完成。它适合希望尽快验证长任务，又愿意接受厂商运行时合同的团队。\n\n公开工程说明将session日志、harness与sandbox解耦，三者可以有不同生命周期。这样环境故障不必等同历史消失，harness也不必永久绑定某台计算机。厂商公布的性能改善来自自己的系统实验，不能直接当企业SLA；真正值得借鉴的是接口分离和权威状态外置。\n\n企业接入前应画清资源映射：本地Task关联哪一个托管session，哪一轮turn和哪份artifact；外部业务操作的稳定ID由谁生成，回调重投由谁去重。不能把托管会话ID当用户登录身份，也不能用供应商完成事件直接替代自己的后置验证。\n\n权限与凭证仍要有外部权威。服务连接工具、代码环境、文件持久化和数据保留可能拥有不同合同，零训练或零保留承诺不能跨功能推断。对客户文书、学生记录与金融资料，分别核对地区、保留、删除、导出与二次使用，并用实际账号执行契约测试。\n\n截至观察日，官方概览明确标Beta，并要求相应beta header；MCP tunnels与dreaming还有更有限的研究预览范围。基础服务开放不表示所有附属能力普遍可用。采购和设计应把版本变化、配额、故障恢复和退出路径列为验证项，不把预览能力写成稳定依赖。\n\n推荐先以一类可核验文件任务对照应用内SDK路线，比较端到端成功、人工时间、尾延迟和成本。若未来需要同一控制层接微调开放模型，托管Claude worker可以是其中一路，业务状态与评测资产仍保持独立。公开资料没有披露的调度和内部评估机制，应继续标为未知，不能按对标产品猜测。\n\n对长时间研究可设一个可迁移产物合同：资料清单、关键claim、证据定位、计算输出、未决问题和验证状态都以通用格式导出。即使托管session以后不可继续，企业仍能阅读已取得结果，或在另一个runtime中从明确边界接续。试验还应在模型处理中、工具等待和产物生成后分别重连，核对事件是否丢失或重投。若服务对某些恢复或删除语义没有明确说明，采购表应保留未知，不用一次成功演示替代长期合同。\n\n## 数据、记忆与模型替换\n\nsession与运行环境分离；持久文件、日志和记忆按具体API独立治理。\n\n厂商托管Claude路线；不能假定支持任意微调开源模型。\n\n## 执行、部署与采用取舍\n\nAnthropic运行harness；sandbox及外部工具按服务配置。托管循环与持久session，日志、harness和环境生命周期分离。通过Claude API调用；Beta与研究预览能力分别检查。\n\n减少完整harness与环境运维；适合云端长任务快速验证。\n\n观察于2026-10-15：Beta；MCP tunnels与dreaming另有研究预览范围。\n\n许可边界：商业服务条款。采用前按实际使用方式核验组件、云服务与模型条款。\n\n## 证据范围与未知\n\n官方概览标Beta；工程文章说明日志、harness、sandbox与凭证边界。\n\n未公开或仍需目标环境验证的部分：企业账号契约测试；区域、配额和采购合同；不同功能删除与导出语义。本页不以产品表面行为推断其隐藏实现。\n\n[Claude Managed Agents：概览](https://platform.claude.com/docs/en/managed-agents/overview)；[Anthropic：Managed Agents工程设计](https://www.anthropic.com/engineering/managed-agents)；[Claude Agent SDK：概览](https://code.claude.com/docs/en/agent-sdk/overview)。",
      "blueprint": {
        "inputs": [
          "Task与托管session配置",
          "获准工具和数据合同",
          "业务状态及验收器"
        ],
        "steps": [
          "建立应用与托管资源映射",
          "提交长任务",
          "处理事件与回调去重",
          "导出产物并独立验收"
        ],
        "outputs": [
          "托管执行结果",
          "可恢复应用状态",
          "采用和退出验证"
        ]
      },
      "citations": [
        {
          "url": "https://platform.claude.com/docs/en/managed-agents/overview",
          "label": "Claude Managed Agents：概览",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://www.anthropic.com/engineering/managed-agents",
          "label": "Anthropic：Managed Agents工程设计",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://code.claude.com/docs/en/agent-sdk/overview",
          "label": "Claude Agent SDK：概览",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": [
        {
          "target": "agent-harness",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent Harness的具体产品路线。"
        },
        {
          "target": "sandbox-lifecycle",
          "type": "implements",
          "reason": "公开能力或可见源码体现沙箱生命周期的具体产品路线。"
        },
        {
          "target": "checkpoint-recovery",
          "type": "complements",
          "reason": "用Checkpoint与恢复检查采用时的控制边界；不推断未公开内部机制。"
        },
        {
          "target": "tool-authorization",
          "type": "implements",
          "reason": "公开能力或可见源码体现工具授权网关的具体产品路线。"
        },
        {
          "target": "agent-session",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent Session的具体产品路线。"
        }
      ],
      "productRoute": {
        "vendor": "Anthropic",
        "category": "托管Agent运行时",
        "execution": "Anthropic运行harness；sandbox及外部工具按服务配置。",
        "orchestration": "托管循环与持久session，日志、harness和环境生命周期分离。",
        "context": "托管服务管理模型context与压缩；应用保存可迁移任务和证据引用。",
        "persistence": "session与运行环境分离；持久文件、日志和记忆按具体API独立治理。",
        "modelBoundary": "厂商托管Claude路线；不能假定支持任意微调开源模型。",
        "deployment": "通过Claude API调用；Beta与研究预览能力分别检查。",
        "license": "商业服务条款",
        "availability": "观察于2026-10-15：Beta；MCP tunnels与dreaming另有研究预览范围。",
        "strengths": "减少完整harness与环境运维；适合云端长任务快速验证。",
        "limits": "待验证或未公开：企业账号契约测试；区域、配额和采购合同；不同功能删除与导出语义。公开能力不等同企业负载与领域任务实测。"
      }
    },
    {
      "id": "cloud-data-contract",
      "title": "云端数据合同与日志治理",
      "parentId": "security",
      "kind": "concept",
      "order": 10,
      "en": null,
      "aliases": [
        "数据保留",
        "Zero data retention",
        "ZDR",
        "DPA"
      ],
      "summary": "逐功能核对保留、地区、删除、二次使用和访问审计。",
      "question": "云API“不用于训练”是否足够？",
      "body": "## 按功能拆开核对\n模型推理、持久会话、文件、向量服务、日志、备份、评测和训练导出可能具有不同保留规则与资格要求。供应商不默认训练API数据，不代表每个功能零保留，也不代表企业自己的网关和trace平台没有存储正文。OpenAI的官方数据控制页按功能列出差异，实际采购应保存当期合同及所用功能清单。\n\n## 企业侧最小化\n先分类个人信息、客户matter、财务资料和公开信息，定义用途、访问角色、存储位置与期限。trace默认记录ID、hash、耗时、token、错误类别和受限payload引用；专家debug读取敏感正文也走角色控制和审计。对第三方观测工具同样检查地区、子处理者和删除能力。\n\n## 可操作合同\n为每种数据列“写入位置、可访问方、目的、最长保留、删除路径、备份限制、训练资格”。API切换或新增功能时重新审查，不能沿用旧模型接口的一句说明。多模型路由也受地区与数据资格限制，低价回退不能绕过政策。\n\n## 验收\n上传带可识别标记的测试资料，检查服务端日志、会话导出、对象存储、trace和供应商删除回执。演练租户导出与退出，明确哪些数据只能等待保留期。本文提供治理方法；具体金融、法律、教育业务的义务取决于机构、法域和用途，应映射到对应专业流程。",
      "blueprint": {
        "inputs": [
          "功能清单",
          "数据分类"
        ],
        "steps": [
          "映射保留与使用条款",
          "最小化记录",
          "演练删除和退出"
        ],
        "outputs": [
          "数据处理矩阵",
          "可核查治理回执"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/your-data",
          "label": "OpenAI：API data controls",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "model-routing",
          "type": "controls",
          "reason": "模型路由必须遵守数据资格。"
        },
        {
          "target": "observability-traces",
          "type": "controls",
          "reason": "观测正文需受限保留与访问。"
        }
      ]
    },
    {
      "id": "delivery-milestones",
      "title": "从只读基线到可靠执行",
      "parentId": "operations",
      "kind": "concept",
      "order": 10,
      "en": null,
      "aliases": [
        "路线图",
        "MVP",
        "里程碑"
      ],
      "summary": "用里程碑的验收条件控制平台复杂度。",
      "question": "第一套企业Agent应该先交付哪些能力？",
      "body": "## M0：资格与任务\n选定一个主结果，收集典型、边界和拒绝案例，定义专家rubric、允许数据和严重错误。20–50个早期任务可帮助发现结构性问题，但不能证明罕见风险安全。同步核查文档许可、权限源、规模、用户角色和预算。\n\n## M1：只读证据链\n接一种资料源，保存原件、版本与ACL，建立hybrid检索和rerank；主Agent交付证据、计算和trace。与最简搜索／固定workflow基线比较：如果动态Agent没有改善质量、时间或人工成本，不急于扩大框架。\n\n## M2：可靠执行\n加入Task／Run、checkpoint、稳定操作ID、工具网关、审批和外部回执。发布门槛包括worker kill/restart、重复事件、超时、取消、过期审批、数据更新与撤权。选择一个恢复权威，避免调度器和框架各自重放副作用。\n\n## M3：受控改进\n离线评测、shadow和canary贯通；prompt、skill、模型或检索变更分别实验，再发布完整版本组合。多Agent和微调只在瓶颈证据支持时引入。\n\n## 人和时间\n业务owner定义成果，专家负责标注与高风险复核，平台负责可靠性，数据owner负责资格，发布负责人管理版本。把工程日、专家日、采购等待和验证周期分开估，不用一个“几周上线”掩盖依赖。",
      "blueprint": {
        "inputs": [
          "主场景",
          "允许数据",
          "早期任务集"
        ],
        "steps": [
          "只读基线",
          "恢复与副作用",
          "评测驱动扩展"
        ],
        "outputs": [
          "阶段验收",
          "下一投资决定"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/building-effective-agents",
          "label": "Anthropic：Building effective agents",
          "kind": "official-doc"
        },
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "task-contract",
          "type": "requires",
          "reason": "每阶段基于明确成功条件。"
        },
        {
          "target": "checkpoint-recovery",
          "type": "requires",
          "reason": "可靠执行依赖恢复权威。"
        },
        {
          "target": "evaluation",
          "type": "requires",
          "reason": "扩展以评测通过为条件。"
        }
      ]
    },
    {
      "id": "eval-security-redteam",
      "title": "安全红队与权限评测",
      "aliases": [
        "提示注入",
        "越权",
        "过度拒绝"
      ],
      "kind": "concept",
      "parentId": "evaluation-targets",
      "order": 10,
      "summary": "在无真实危险副作用的环境中检验注入、越权、审批漂移与信息外传，同时测合法任务表现。",
      "question": "如何发现攻击成功，同时避免正常业务被过度拒绝？",
      "body": "## 攻击成功和合法任务都要测\n安全评测既要检查攻击能否越界，也要检查正常用户是否仍能完成工作。把所有请求拒绝会降低攻击成功率，却不构成可用企业Agent。按资产、主体、入口、可能副作用和损失定义威胁模型，再构造可重放任务；危险动作在无真实资金、数据外传或生产写入的环境中测试。\n\n## 覆盖不可信数据入口\n除了用户直接越狱，还要测试检索文档、网页、工具结果、附件和memory中的间接指令。攻击可能诱导改写任务、泄漏凭据、调用无关工具、把假事实写进长期记忆，或将私有信息带到另一渠道。应检查系统最终动作与信息流，不能只判断回答是否包含某个危险词。\n\n## 权限状态也会变化\n测试审批参数被替换、批准过期、重复回调、并发撤权、跨租户缓存命中、共享环境中其他角色的文件与登录。模型请求能力不等于执行授权；身份、policy、工具网关和数据层执行硬限制。红队验证这些边界实际生效，而不是检查system prompt是否写了“请遵守权限”。\n\n## 用可解释指标管理改进\n分别报告攻击成功率、合法任务成功率、过度拒绝、严重外传和未授权动作。按攻击家族与任务风险切片，保留judge误判和人工裁决；多个模型一致不代表真值。一次修复后跑既有攻击回归和未见变体，避免仅记住测试文本。高风险检查不能由文风评分抵消；无结论或评测器故障应显式记录，不能默认为安全通过。\n\n攻击语料、判分器和合法任务集应分别版本化。上线后的新攻击进入候选池，经确认再扩回归集；留出未参与防御调优的变体，观察防线是否只记住了攻击表述。\n\n## 攻击用例必须绑定资产\n对每个攻击写清攻击者控制的是网页、附件、工具字段还是历史记忆，目标是读出秘密、绕过批准还是污染未来任务。成功判定检查实际状态或可见数据，模型说愿意越权不必然代表系统已被攻破；模型拒绝也不证明后续工具未执行。对防护后的正常任务建立对照，记录误拒和新增延迟。新增连接器与权限变更后补对应威胁用例。",
      "blueprint": {
        "inputs": [
          "威胁模型与硬权限",
          "文档工具memory攻击",
          "正常请求对照集"
        ],
        "steps": [
          "注入直接和间接攻击",
          "测撤权审批漂移及外传",
          "检查租户缓存及污染",
          "同时统计攻击成功与过拒"
        ],
        "outputs": [
          "攻击证据及严重等级",
          "防线缺口和正常任务代价"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc",
          "note": "2026-01-09；官方方法背景，具体合同与阈值须按业务验证。"
        }
      ],
      "links": [],
      "en": "Security Red Teaming"
    },
    {
      "id": "foundations",
      "title": "任务与总体架构",
      "parentId": null,
      "kind": "domain",
      "order": 10,
      "en": null,
      "aliases": [],
      "summary": "先确定业务结果、责任与边界，再选择执行框架。",
      "question": "企业究竟要把什么任务交给 Agent？",
      "body": "## 三条主线\n企业 Agent 的结构可以沿三条流理解。执行流把目标变成任务、模型行动、工具调用和候选产物；证据流把原始资料变成有权限、有版本、可定位的上下文；改进流把产物与轨迹变成评测、故障分析和新版本。三条流共享身份、版本和审计，但各自有独立的事实来源。\n\n## 从结果倒推系统\n先写清“谁在什么时间范围内，使用哪些数据，允许采取哪些动作，交付什么可验证结果”。金融研究、课程辅导、法律研究的成功条件不同。可复算的财务表、延迟测验中的独立作答、引证原文与效力核验，都比“回答看起来专业”更接近业务成果。\n\n本图谱将导航层级与依赖关系分开：树决定概念存放位置，关系解释系统怎样工作。框架、模型和数据库是可替换实现；任务、证据和权限合同应由企业掌握。具体术语、选型判断和参考架构从以下节点展开。",
      "blueprint": {
        "inputs": [
          "业务目标",
          "数据资格"
        ],
        "steps": [
          "定义任务合同",
          "划分系统责任",
          "建立最简基线"
        ],
        "outputs": [
          "可验收任务",
          "模块边界"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/building-effective-agents",
          "label": "Anthropic：Building effective agents",
          "kind": "official-doc"
        },
        {
          "url": "https://developers.openai.com/api/docs/guides/agents-api/architecture",
          "label": "OpenAI：Agents API architecture",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "identity-authorization",
      "title": "身份、租户与授权边界",
      "parentId": "security",
      "kind": "concept",
      "order": 10,
      "en": null,
      "aliases": [
        "RBAC",
        "ABAC",
        "租户隔离",
        "IDOR"
      ],
      "summary": "授权主体来自服务端凭证，并传播到每个工具和数据访问点。",
      "question": "怎样防止模型替用户扩大访问范围？",
      "body": "## 谁在行动\n每次请求从服务端验证的token或会话取用户、租户、角色和项目范围。工具参数里出现user_id只是资源选择输入，不能覆盖已验证主体。Agent定义、Session、Task和Run分别引用授权上下文；子Agent委派只能缩小范围，不能因为换了执行单元获得新权限。\n\n## 三层检查\n入口校验用户能否创建任务，工具/API校验每个动作与资源，数据库或数据服务执行最终行级／对象级限制。前端隐藏按钮提供体验而非安全边界。检索必须在候选进入reranker和prompt之前过滤，避免仅在最终回答时遮盖已泄漏内容。\n\n## 动态权限与执行点\n长任务不能只在启动时检查一次。写操作在实际调用点重新确认策略、资源版本、审批有效期和执行租约；高风险读也需处理撤权。把策略版本、授权决定和请求hash记录在事件中，便于解释当时为什么允许。\n\n## 验证\n用同一问题、相似文件名和不同角色建立对照，检查候选、工具结果、摘要、日志和产物都没有跨租户信息。再在运行中撤销权限，确认后续调用停止，已生成候选被标记需复核。缓存键若缺tenant、ACL版本或scope，即使数据库本身正确也可能绕开隔离。",
      "blueprint": {
        "inputs": [
          "已验证主体",
          "资源与动作"
        ],
        "steps": [
          "传播最小scope",
          "执行点授权",
          "记录策略与版本"
        ],
        "outputs": [
          "允许或拒绝",
          "审计决定"
        ]
      },
      "citations": [
        {
          "url": "https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices",
          "label": "MCP：Security best practices",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "tool-authorization",
          "type": "controls",
          "reason": "工具层落实动作授权。"
        },
        {
          "target": "retrieval",
          "type": "controls",
          "reason": "检索候选必须受主体范围限制。"
        },
        {
          "target": "cache-invalidation",
          "type": "controls",
          "reason": "权限变化触发相关缓存失效。"
        }
      ]
    },
    {
      "id": "instruction-roles",
      "title": "指令角色与信任边界",
      "en": "Instruction Roles",
      "aliases": [
        "System Prompt",
        "Developer Prompt",
        "User Prompt"
      ],
      "kind": "concept",
      "parentId": "models-context",
      "order": 10,
      "summary": "区分应用规则、用户目标与外部资料在模型输入中的职责。",
      "question": "怎样设计指令角色与信任边界，并验证其对任务质量与可靠性的影响？",
      "body": "区分应用规则、用户目标与外部资料在模型输入中的职责。\n\nsystem、developer、user等角色是供应商定义的API语义，不是可以机械对应的行业统一层级。应用需要表达稳定行为规则，用户需要提供具体目标和偏好，检索与工具结果则提供待判断数据。适配不同模型时，应确认各自角色、原生系统字段和优先级支持，而不是简单改字段名。\n\nOpenAI当前prompt文档将developer用于应用指令，并说明它相对user的优先关系。其他供应商可能使用不同结构。企业可以先维护与供应商无关的规则模块，再由adapter按模型语义渲染。渲染过程与变量schema应有版本，确保一条用户输入不会被错误拼进高优先级规则。\n\n应用规则适合约束任务范围、证据标准、允许工具、停止条件与输出合同；领域模块补充财报口径、法域或教学策略。用户输入提供对象、日期和成功条件。网页、上传文档、代码注释和MCP返回即使包含“忽略之前规则”，也只是外部内容。XML、Markdown标题或引用符可以帮助阅读，却不能独立防止prompt injection。\n\n把规则写成可观察要求，比“你是世界顶尖专家”更容易验证。例如要求关键数值回到原报表并复算，要求法律引文核原文与适用日期，要求提示后答案与独立作答分开记录。不要用一份巨型system prompt补所有历史错误，局部多步骤方法可放入按需加载模块。\n\n提示词只能辅助执行控制。即使模型遵守角色规则，服务器仍要校验主体、资源和动作；即使模型被外部材料诱导，也应无法扩大权限。测试在不同数据通道注入伪指令，观察模型回应与真实工具效果分别如何。一个模型拒绝了单轮攻击，不证明跨摘要、memory和子Agent后的安全性。\n\n产品需要展示简明行动依据、证据与操作记录，不必索取私有思维链。把可审计性建立在真实事件上，能避免把一段说服力很强的自述误当执行证明。\n\n**实践重点**：按供应商角色语义适配system/developer/user；检索和工具返回保留为数据，授权由执行器判断。\n\n**验证抓手**：用检索资料中伪造指令测试规则不被改写，并检验工具侧真实权限。\n\n**常见误区**：把网页内容拼入高优先级prompt，或把分隔标签当可靠安全边界。\n\n[OpenAI：Prompt engineering](https://developers.openai.com/api/docs/guides/prompt-engineering)；[Anthropic：Context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)。",
      "blueprint": {
        "inputs": [
          "应用与领域规则",
          "用户任务变量",
          "供应商角色语义"
        ],
        "steps": [
          "区分指令和外部数据",
          "校验变量并渲染角色",
          "阻止资料改写规则",
          "执行层独立校验权限"
        ],
        "outputs": [
          "版本化角色消息",
          "明确数据边界",
          "指令遵循与攻击测试"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/prompt-engineering",
          "label": "OpenAI：Prompt engineering",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents",
          "label": "Anthropic：Context engineering",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "model-adapter",
          "type": "requires",
          "reason": "本节点的设计需要先明确模型适配层。"
        },
        {
          "target": "tool-authorization",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具授权网关。"
        }
      ]
    },
    {
      "id": "latency-critical-path",
      "title": "端到端延迟关键路径",
      "en": "End-to-end Critical Path",
      "aliases": [
        "TTFT",
        "尾延迟",
        "任务时延"
      ],
      "kind": "concept",
      "parentId": "performance-delivery",
      "order": 10,
      "summary": "用排队、模型、检索、工具和验证组成的关键路径解释完成时间。",
      "question": "怎样设计端到端延迟关键路径，并验证其对任务质量与可靠性的影响？",
      "body": "用排队、模型、检索、工具和验证组成的关键路径解释完成时间。\n\nAgent延迟需要分三种体验：用户提交到首个可见token、第一条有用且可核验信息到达，以及任务通过验收并获得产物。流式输出可以改善感知，却不一定缩短业务完成时间。一个很快开始说话、随后持续空泛解释的Agent，未必比稍晚返回正确证据更有用。\n\n总耗时由关键路径组成：排队、身份与context、检索和重排、每轮模型prefill与decode、工具、合并及验证。串行轮次累加，真正独立的并行分支取最长分支，再加调度与合并开销。组件p95不能直接相加得到端到端p95，因为负载相关性与尾部事件分布不同。\n\n先通过trace定位时间花在哪里，再做优化。重复搜索、过长工具输出、无意义自评和多余模型往返通常值得优先处理；然后比较模型档位、输出长度、缓存与预热。不要先把数据库换掉，却没有证据表明检索是瓶颈。强行并行有依赖的操作也可能降低正确性。\n\n不同任务制定不同SLO。交互知识问答重视首次有用响应，异步多源研究重视可验证进度与最终完成，写操作重视后置状态确认。指标应按租户、任务类型、冷暖缓存、数据规模和供应商分层，而非用全站平均值掩盖困难场景。\n\n公开厂商工程文章中的提速数字反映其系统和负载，不能直接成为企业SLA。试验用同一任务、模型配置、数据与验收比较方案，并保留失败和重试，不只挑成功的最快运行。\n\n优化还要看质量成本：省掉verifier可能更快，却提高严重错误；缩短输出可能降低阅读负担，也可能遗漏证据。报告延迟时同时报告任务成功、人工修订和费用，才能判断改进是否真实。\n\n**实践重点**：区分首token、首条有用证据和验收完成；并行取最长分支。\n\n**验证抓手**：在代表负载下测端到端p50/p95/p99和各阶段trace。\n\n**常见误区**：把各组件p95相加，或把流式输出当业务提速。\n\n[OpenAI：Latency optimization](https://developers.openai.com/api/docs/guides/latency-optimization)；[Anthropic：Managed Agents工程设计](https://www.anthropic.com/engineering/managed-agents)。",
      "blueprint": {
        "inputs": [
          "端到端trace",
          "任务类型与负载",
          "质量和SLO目标"
        ],
        "steps": [
          "分解阶段及关键路径",
          "识别重复和等待",
          "优化调用并行与输入",
          "在代表负载验证尾延迟"
        ],
        "outputs": [
          "首证据与完成时间",
          "瓶颈归因",
          "有质量约束的SLO"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/latency-optimization",
          "label": "OpenAI：Latency optimization",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://www.anthropic.com/engineering/managed-agents",
          "label": "Anthropic：Managed Agents工程设计",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "agent-loop",
          "type": "requires",
          "reason": "本节点的设计需要先明确Agent执行循环。"
        },
        {
          "target": "parallel-result-merge",
          "type": "requires",
          "reason": "本节点的设计需要先明确并行结果合并。"
        }
      ]
    },
    {
      "id": "learning-skill-promotion",
      "title": "Skill与能力候选晋升",
      "aliases": [
        "技能晋升",
        "fresh audit",
        "撤销"
      ],
      "kind": "concept",
      "parentId": "learning-improvement",
      "order": 10,
      "summary": "把可复用方法先作为带适用范围和验证条件的候选，经过回归与灰度后才进入正式能力目录。",
      "question": "一次成功经验怎样成为有前提、可验证、可撤销的技能？",
      "body": "## 把方法当可审查的能力资产\nSkill和runbook保存如何做一类任务，不应只是某次对话的压缩。候选记录适用任务、所需输入、前置权限、步骤、验证方法、输出、异常、禁用条件、依赖与来源trace。将领域方法与客户事实分开，避免把某家公司当前数字或某位学生私人观察推广成团队规则。\n\n## 先在隔离区提出改变\n允许Agent从失败和专家修订提出skill或harness diff，但不直接改正式policy、隐藏grader、权限和发布指针。候选须说明针对哪个根因以及预期收益；来自单次顺利演示的方法仍需补充失败处理和边界测试。没有来源或仅靠模型自评的技巧应保留为假设。\n\n## 晋升检验可迁移性\n开发集用于完善方法，回归集检查已承诺行为，未见任务和fresh audit观察泛化。按任务类型测成功、严重错误、人工修订、费用与尾延迟；必要时进行专家抽审和受控灰度。固定适用范围，不用整体高分掩盖一个高风险切片退化。反复优化某case后，应承认它已进入训练反馈，而不再当未见证据。\n\n## 生命周期包含撤销\n正式能力目录绑定版本、owner、依赖和兼容的工具或模型；运行记录使用了哪个版本。来源更新、接口变化、用户撤权或新模型出现时重新评估，过时方法可停用并回滚。回滚skill不自动撤销它产生的memory和外部动作，须沿lineage检查影响。系统积累新能力，意味着经验证的方法在新任务上稳定改善，而不是目录文件越来越多。",
      "blueprint": {
        "inputs": [
          "方法来源及证据",
          "前提和适用scope",
          "目标及不可退化任务"
        ],
        "steps": [
          "只提交候选diff和测试",
          "审安全可迁移性及收益",
          "用隐藏集fresh audit验证",
          "晋升版本并保留撤销"
        ],
        "outputs": [
          "带前提的skill版本",
          "评测依据与失效条件"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent评测方法",
          "kind": "official-doc",
          "note": "学习收益需在独立业务任务验证。"
        }
      ],
      "links": [
        {
          "target": "eval-holdout-contamination",
          "type": "requires",
          "reason": "反复优化后需要fresh audit。"
        },
        {
          "target": "eval-release-rollback",
          "type": "requires",
          "reason": "技能变更也有晋升和撤销。"
        }
      ],
      "en": "Skill Promotion"
    },
    {
      "id": "model-adapter",
      "title": "模型适配层",
      "en": "Model Adapter",
      "aliases": [
        "Provider Adapter",
        "模型网关适配"
      ],
      "kind": "concept",
      "parentId": "models-contracts",
      "order": 10,
      "summary": "把供应商消息、流、工具和usage转换为应用可控接口。",
      "question": "怎样设计模型适配层，并验证其对任务质量与可靠性的影响？",
      "body": "把供应商消息、流、工具和usage转换为应用可控接口。\n\n模型适配层让应用用稳定接口处理不同供应商，但不能把差异抹平。接口通常覆盖message、tool request、tool result、structured output、usage、error、stream和cancel；同时保留受控native扩展。企业可以更换模型服务，而不必重写业务工具和证据数据模型。\n\nOpenAI Agents SDK公开Model接口要求工具调用有稳定非空call ID，并提供provider资源管理与重试建议边界。这比把base_url替换后请求成功更具体。真实兼容还涉及消息角色、工具结果序列、并行调用、finish reason、refusal、reasoning参数以及断流后能否安全恢复。\n\n内部事件模型应区分文本delta、完整工具调用、usage更新、最终输出和错误。不要假设所有供应商在同一时刻给出完整参数，也不要把未知停止原因默认为成功。原始provider metadata可受限保存，统一字段用于业务逻辑；缺少信息应标未知，而不是虚构一个默认值。\n\n能力检测与适配分开。adapter转换协议，capability registry记录某模型能否使用严格schema、原生搜索、缓存和compaction。不能支持的能力应明确失败或降级，例如改用应用检索，而非静默丢弃工具。跨模型的opaque reasoning状态通常不可移植，需要从可读事件和证据重建输入。\n\n连接池、WebSocket生命周期、超时和关闭同样属于adapter。失效连接的自动恢复要受业务重放合同约束；已产生工具效果后不能盲目重送整个请求。usage映射应保留缓存读写和输出分类，才能与账单核对。\n\n契约测试使用同一组非敏感样例覆盖中文参数、日期、数值、多工具、空输出、拒绝、截断与取消，再在真实harness任务上评估。通过协议测试只说明接口能工作，不说明该模型足以完成金融、教育或法律任务。\n\n适配错误应独立归因。例如一个模型没有返回usage，并不意味着本次费用为零；缺少某种finish reason也不能转换成正常完成。应用应保留未知，供监控和计费对账处理，避免统一接口制造错误确定性。\n\n**实践重点**：统一基础事件，保留native能力与错误；管理连接和关闭。\n\n**验证抓手**：对工具、schema、stream、取消与token核算跑conformance。\n\n**常见误区**：base_url能回答你好就认定完整Agent兼容。\n\n[Agents SDK：Model接口和call ID约束](https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/models/interface.py#L37-L80)；[OpenAI Agents SDK：模型与provider](https://developers.openai.com/api/docs/guides/agents/models)。",
      "blueprint": {
        "inputs": [
          "供应商SDK和模型ID",
          "统一消息及事件schema",
          "业务工具合同"
        ],
        "steps": [
          "转换消息与流事件",
          "保留native特性和错误",
          "配对工具及结果",
          "管理连接和usage"
        ],
        "outputs": [
          "稳定应用接口",
          "可解释能力差异",
          "Conformance测试结果"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/models/interface.py#L37-L80",
          "label": "Agents SDK：Model接口和call ID约束",
          "kind": "code",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://developers.openai.com/api/docs/guides/agents/models",
          "label": "OpenAI Agents SDK：模型与provider",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "tool-contract",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具接口合同。"
        }
      ]
    },
    {
      "id": "model-routing",
      "title": "模型路由",
      "en": "Model Routing",
      "aliases": [
        "模型路由",
        "Router"
      ],
      "kind": "concept",
      "parentId": "models-release",
      "order": 10,
      "summary": "按任务风险、复杂度、时限与数据范围选择模型。",
      "question": "怎样设计模型路由，并验证其对任务质量与可靠性的影响？",
      "body": "按任务风险、复杂度、时限与数据范围选择模型。\n\n路由把任务分配给适当模型，是一个会影响质量的决策系统。输入可以包括任务类型、风险、复杂度、数据敏感性、上下文大小、deadline与成本。建议先采用可解释的确定性规则，再根据真实失败数据评估学习型router，避免一开始增加难以归因的模型决策层。\n\n先做资格筛选，再做成本与能力选择。某模型可能响应很快，却不能接收客户保密资料，或不支持必要工具；它不应进入候选集合。金融算术可以交确定性代码，快速分类、压缩、生成和judge可以各用不同模型，但每个角色都需要独立版本和质量记录。\n\n选择指标应是通过验收的完整任务成本，而非输入token单价。便宜模型若需要更多循环、搜索、重试和人工返工，可能更贵；高档模型也不必用于所有步骤。路由要记录选择理由、实际调用、后续升级与最终质量，使团队知道难任务是否被错误送给低能力路径。\n\n可设有限升级机制：低成本路径在证据不足、结构错误或无进展时，转到获准高档模型；升级仍受剩余预算和数据合同约束。不能无限来回切换，更不能把judge分数低直接解释为模型不够强，忽略检索或工具缺陷。\n\n评估要按任务和风险分层，尤其检查错分到便宜模型的严重错误。线上比较保留冷缓存、供应商配额和人工接管影响，不把某一时段低延迟当长期优势。路由模型本身升级时也需要回归。\n\n对业务方可展示策略而非所有内部细节，例如普通材料先走标准路径，明确高风险或复杂问题进入专家路径。策略必须能解释何时降级、排队和停止；不应为了完成率而把未批准供应商静默加入。\n\n**实践重点**：先做确定性规则；记录理由与质量，再评估学习型router。\n\n**验证抓手**：评测路由误分、尾延迟和有效结果成本。\n\n**常见误区**：便宜模型多循环和人工返工反而更贵。\n\n[OpenAI：模型目录](https://developers.openai.com/api/docs/models)；[OpenAI Agents SDK：模型与provider](https://developers.openai.com/api/docs/guides/agents/models)。",
      "blueprint": {
        "inputs": [
          "任务风险和复杂度",
          "获准模型能力矩阵",
          "Deadline与成本目标"
        ],
        "steps": [
          "筛选数据和功能资格",
          "按任务规则选模型",
          "记录升级及理由",
          "用实际结果评估路由"
        ],
        "outputs": [
          "模型选择决定",
          "质量与费用轨迹",
          "可解释降级路径"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/models",
          "label": "OpenAI：模型目录",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://developers.openai.com/api/docs/guides/agents/models",
          "label": "OpenAI Agents SDK：模型与provider",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "model-capability-registry",
          "type": "requires",
          "reason": "本节点的设计需要先明确模型能力注册。"
        },
        {
          "target": "effective-result-cost",
          "type": "requires",
          "reason": "本节点的设计需要先明确有效结果成本。"
        }
      ]
    },
    {
      "id": "models-context",
      "title": "Prompt与Context",
      "en": "Prompts and Context",
      "aliases": [],
      "kind": "branch",
      "parentId": "models",
      "order": 10,
      "summary": "选择模型每步看到的规则与资料，并把指令作为发布资产。",
      "question": "怎样把Prompt与Context落实为可比较和可验证的工程选择？",
      "body": "指令角色决定应用规则与用户目标怎样表达，context builder决定哪些证据和状态进入本步，registry保存版本与适用范围。三者共同影响质量，但都不能取代执行层授权。保持模块短小、来源可回查，并对旧模型补丁做消融。\n\n[OpenAI：Prompt engineering](https://developers.openai.com/api/docs/guides/prompt-engineering)；[Anthropic：Context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)。",
      "blueprint": {
        "inputs": [
          "规则模块",
          "任务和外部资料"
        ],
        "steps": [
          "区分信任角色",
          "渲染版本化Prompt",
          "选择必要context"
        ],
        "outputs": [
          "模型输入视图",
          "版本和来源引用"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/prompt-engineering",
          "label": "OpenAI：Prompt engineering",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents",
          "label": "Anthropic：Context engineering",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": []
    },
    {
      "id": "observability-traces",
      "title": "Task／Run观测与成本归因",
      "parentId": "operations",
      "kind": "concept",
      "order": 10,
      "en": null,
      "aliases": [
        "Tracing",
        "OpenTelemetry",
        "可观测性"
      ],
      "summary": "把检索、模型、工具、验证串成可定位的执行证据。",
      "question": "失败发生在哪层，为什么花了这些时间和钱？",
      "body": "## 根与跨度\ntrace以Task／Run为根，子span覆盖context、retrieval、rerank、model、tool、verification和memory。记录开始结束、状态、父子关系、版本、token、费用与受限证据引用。并发span相加不等于端到端延迟；需区分关键路径、排队与实际服务时间。\n\nOpenTelemetry GenAI语义约定在独立仓库演进，实施时固定规范与instrumentation版本。业务事件和供应商属性通过适配转换，不能将某个trace平台的私有schema变成唯一事实。任务事件保留事实，摘要只是便于阅读的视图。\n\n## 可回答的问题\n按任务家族和版本看成功、严重失败、p50／p95、人工分钟和有效结果成本；区分供应商限流、索引陈旧、工具错误与模型推理失误。关联发布版本和动态数据快照，避免把某次知识更新造成的变化误归因给模型。\n\n## 隐私与证据\n无需收集模型隐藏推理链来证明可靠性。保留工具请求、证据、可见决策、回执与产物足以支持多数审计；敏感正文以受控引用存储，调试访问有记录。观测本身可能成为跨租户泄漏通道。\n\n## 验证\n注入一次检索超时、一次工具未知效果和一次validator失败，确认看板能分层归因；对账真实供应商用量与内部账本，覆盖失败重试和后台任务。trace完整不证明业务正确，仍要检查结果后置条件。",
      "blueprint": {
        "inputs": [
          "Task/Run事件",
          "调用与费用"
        ],
        "steps": [
          "关联span和版本",
          "脱敏并归因",
          "按任务slice聚合"
        ],
        "outputs": [
          "故障定位",
          "延迟与成本看板"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/open-telemetry/semantic-conventions-genai",
          "label": "OpenTelemetry：GenAI semantic conventions",
          "kind": "code"
        }
      ],
      "links": [
        {
          "target": "execution-run",
          "type": "requires",
          "reason": "Run提供稳定执行身份。"
        },
        {
          "target": "latency-critical-path",
          "type": "feeds",
          "reason": "时间跨度用于定位关键路径。"
        },
        {
          "target": "effective-result-cost",
          "type": "feeds",
          "reason": "费用和结果用于单位经济性。"
        }
      ]
    },
    {
      "id": "openai-agents-sdk",
      "title": "OpenAI Agents SDK",
      "en": "OpenAI Agents SDK",
      "aliases": [
        "Agents SDK",
        "openai-agents-python"
      ],
      "kind": "product",
      "parentId": "products-frameworks",
      "order": 10,
      "summary": "在自己的应用中控制Agent、工具、handoff和会话的SDK。",
      "question": "它怎样运行Agent，哪些状态和权限仍由应用负责？",
      "body": "观察时点：2026-10-15。在自己的应用中控制Agent、工具、handoff和会话的SDK。\n\n## 已公开的技术路线与控制边界\n\nPython runner驱动模型与工具；Session协议与ModelProvider提供扩展边界。应用负责部署、存储、批准和工具资源；SDK负责循环及相关状态处理。\n\nAgents SDK适合希望在自己应用中掌握部署、存储、权限和工具执行的团队。SDK提供Agent、工具、handoff、guardrail与runner等抽象，应用将这些构件嵌入自己的服务。它与厂商托管Agents API不同，运行环境和业务控制并不会自动交给OpenAI管理。\n\n固定Python源码的Session协议包含历史读取、追加、弹出和清空，是可替换存储后端的边界。但conversation history并不是完整长期记忆系统；来源、冲突、TTL、删除、跨租户scope和能力准入仍要应用设计。源码还对会话写入取消和压缩快照替换作了特殊处理，提示持久化操作不能简单跟随模型流一起中断。\n\n公开Model接口要求tool call ID非空且在Run和恢复链中稳定，变化后的工具身份或参数不能复用旧ID。这是适配第三方模型时必须测试的合同。更换模型字符串或base_url后能回答普通问题，不能证明并行工具、schema、拒绝、stream和恢复都兼容。\n\nGuardrail也有执行时序。固定run loop区分并行和阻断检查，并在某些sandbox准备前运行blocking guardrail。降低延迟时不能把决定能否产生副作用的检查放到动作之后。企业工具网关仍要独立检查身份、资源和批准，不能只依赖模型侧安全提示。\n\nMIT许可与清晰接口有利于依赖集成。推荐保留一个主runtime，把企业Task、证据、操作账本和评测放在自有层；若已有LangGraph或持久引擎，不要让两层各自重新播放同一动作。框架之间可以组合，但需明确谁拥有循环、等待和恢复。\n\n验证从协议到真实harness逐层进行：会话重启、并行调用、approval恢复、取消、输出拒绝和未知工具结果；随后用三域任务测证据、计算与业务结果。公开源码和发布元数据能够说明实现入口，不能证明目标云环境、第三方adapter或企业负载已通过。\n\n一个可验证的接口切片是：Session实现保存对话，业务Task表保存目标和验收，ToolOperation表保存副作用身份，Artifact保存产物和证据映射。四者通过稳定ID关联，不需要挤进同一messages数组。先用测试后端验证工具成功后丢响应、重复恢复和批准参数变化，再接正式业务。对provider切换，保留原始事件与统一视图的对照，检查call ID、usage和最终状态是否一致。若项目已用另一工作流，先限定SDK只负责一个局部Agent，不让它和外层各自重放同一动作。\n\n## 数据、记忆与模型替换\n\nSession协议保存conversation history；企业长期记忆的来源、TTL和权限需另行设计。\n\n有模型与provider接口；第三方适配须验证schema、stream、call ID与native能力。\n\n## 执行、部署与采用取舍\n\nSDK进程在应用选择的环境中运行；工具和数据库由应用管理。Runner驱动模型、工具、handoff及恢复相关状态。自有云服务或受控worker；不是托管Agents API。\n\n轻量依赖集成与明确Session/Model边界，适合OpenAI原生或经验证provider。\n\n观察于2026-10-15：源码与v0.24.0发布状态观察于2026-10-15；v0.24.0；SHA 17d994bd3045dae71acda676a4ef4762ed8ecd94\n\n许可边界：MIT。采用前按实际使用方式核验组件、云服务与模型条款。\n\n## 证据范围与未知\n\n固定源码已读Session、Model接口和guardrail先后边界；MIT文件已核。\n\n未公开或仍需目标环境验证的部分：企业负载表现；第三方适配覆盖率；外部副作用端到端一致性。本页不以产品表面行为推断其隐藏实现。\n\n[Agents SDK：Session接口源码](https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/memory/session.py#L53-L94)；[Agents SDK：Model接口和call ID约束](https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/models/interface.py#L37-L80)；[Agents SDK：阻断检查与sandbox初始化](https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/run_internal/run_loop.py#L1360-L1395)；[Agents SDK：MIT许可](https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/LICENSE)；[OpenAI Agents SDK：模型与provider](https://developers.openai.com/api/docs/guides/agents/models)。",
      "blueprint": {
        "inputs": [
          "Agent定义和工具schema",
          "自有存储及部署",
          "模型provider与业务权限"
        ],
        "steps": [
          "在应用内运行runner",
          "通过Session接口管理历史",
          "校验工具和guardrail边界",
          "持久化并外层验收"
        ],
        "outputs": [
          "应用内Agent结果",
          "会话与调用轨迹",
          "可替换存储和模型接口"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/memory/session.py#L53-L94",
          "label": "Agents SDK：Session接口源码",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/models/interface.py#L37-L80",
          "label": "Agents SDK：Model接口和call ID约束",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/run_internal/run_loop.py#L1360-L1395",
          "label": "Agents SDK：阻断检查与sandbox初始化",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/LICENSE",
          "label": "Agents SDK：MIT许可",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://developers.openai.com/api/docs/guides/agents/models",
          "label": "OpenAI Agents SDK：模型与provider",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": [
        {
          "target": "agent-loop",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent执行循环的具体产品路线。"
        },
        {
          "target": "agent-session",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent Session的具体产品路线。"
        },
        {
          "target": "model-adapter",
          "type": "complements",
          "reason": "用模型适配层检查采用时的控制边界；不推断未公开内部机制。"
        },
        {
          "target": "tool-call-correlation",
          "type": "implements",
          "reason": "公开能力或可见源码体现工具调用ID配对的具体产品路线。"
        },
        {
          "target": "tool-authorization",
          "type": "implements",
          "reason": "公开能力或可见源码体现工具授权网关的具体产品路线。"
        }
      ],
      "productRoute": {
        "vendor": "OpenAI",
        "category": "应用内Agent SDK",
        "execution": "SDK进程在应用选择的环境中运行；工具和数据库由应用管理。",
        "orchestration": "Runner驱动模型、工具、handoff及恢复相关状态。",
        "context": "应用提供Agent指令和工具，Session接口保存会话历史，原生能力依provider。",
        "persistence": "Session协议保存conversation history；企业长期记忆的来源、TTL和权限需另行设计。",
        "modelBoundary": "有模型与provider接口；第三方适配须验证schema、stream、call ID与native能力。",
        "deployment": "自有云服务或受控worker；不是托管Agents API。",
        "license": "MIT",
        "availability": "观察于2026-10-15：源码与v0.24.0发布状态观察于2026-10-15；v0.24.0；SHA 17d994bd3045dae71acda676a4ef4762ed8ecd94",
        "strengths": "轻量依赖集成与明确Session/Model边界，适合OpenAI原生或经验证provider。",
        "limits": "待验证或未公开：企业负载表现；第三方适配覆盖率；外部副作用端到端一致性。公开能力不等同企业负载与领域任务实测。"
      }
    },
    {
      "id": "openai-dots",
      "title": "OpenAI dots",
      "en": "OpenAI dots",
      "aliases": [
        "dots",
        "Your dot",
        "GPT-Dot"
      ],
      "kind": "product",
      "parentId": "products-personal",
      "order": 10,
      "summary": "用持续Agent身份协调多个任务和消息入口的云端产品。",
      "question": "它怎样运行Agent，哪些状态和权限仍由应用负责？",
      "body": "观察时点：2026-10-15。用持续Agent身份协调多个任务和消息入口的云端产品。\n\n## 已公开的技术路线与控制边界\n\n常驻协调者＋独立后台任务＋电脑/浏览器及连接服务。消费产品使用文档不等于开放dots runtime或SDK；自有产品另选公开API与接口。\n\ndots首先是持续Agent产品，而不是可直接fork的企业框架。官方描述云端常驻的协调者，拥有电脑和浏览器，可在用户设备离线时继续工作，并跨ChatGPT、Slack和Teams等入口协调任务。GPT-Dot可作为检索别名；本页以官方dots产品为准，不另行推断未经证实的开发平台。\n\n最值得学习的产品合同是持续身份与独立任务分开。用户面对同一个dot调整优先级，后台工作可以拥有自己的线程和产物。企业数据模型可让Agent identity关联多个Task、Run和Session，而不必依赖一份无限增长、永不结束的context。长期协调不等于所有任务共享全部可见信息。\n\n官方Tasks and memory文档区分当前context、ChatGPT saved memory和dot保存的notes。notes不是完整逐字稿，改变ChatGPT memory设置也不必然改变已经形成的笔记。委派任务获得需要的上下文，而非自动得到用户全部会话。产品中“记住了什么”和“保存了哪段聊天”因此需要不同管理入口。\n\n对企业而言，消息渠道、app访问与电脑连接应分别授权，具备明确owner和scope。任务进行时改变范围，要更新合同并检查已有产物。云端继续工作也带来取消、等待、通知和回执责任；任务结束并不自动证明最终结果正确或已经外部交付。\n\n公开页面当前描述使用GPT-6 Astra并逐步向eligible accounts开放；这不能证明所有地区或企业账号普遍可用，也不能说明用户可以任意替换基座。使用文档没有公开内部memory数据库、调度算法、完整system prompt或grader，本页将其保留为未知。\n\n开发自有产品应另选已公开Agents API、SDK、Codex集成或plugin接口，不假定消费产品全部能力可以嵌入。可把dots当产品设计参照，用任务可追踪性、权限可解释性和长期协作体验验证自己的方案；不能将厂商功能公告当企业任务成功率或安全性实测。\n\n一个企业式持续协调者可以维护有限的任务清单和优先级，把每份研究或教案委派为有独立验收的Task，完成后只吸收经过复核的稳定观察。它不应将每次临时偏好自动升级为组织规则，也不能在跨渠道时扩大资料可见范围。用户改变memory设置、删除任务或撤回连接时，界面应说明notes、历史、文件和后台工作分别怎样处理。这些是从公开产品合同推导的设计建议，并非已披露的dots内部实现，更不是消费账号权限可直接用于第三方企业产品的证明。\n\n## 数据、记忆与模型替换\n\n当前context、ChatGPT saved memory和dot notes分开；子任务只获得需要的上下文。\n\n官方当前描述使用GPT-6 Astra；不能据此推断用户可替换任意基座。\n\n## 执行、部署与采用取舍\n\n官方描述云端常驻电脑与浏览器，用户设备离线时可继续。稳定协调者委派独立后台任务，并跨消息入口延续身份。ChatGPT及官方支持渠道；eligible accounts逐步开放。\n\n持续身份与任务分离的产品合同值得借鉴；不等于开放runtime。\n\n观察于2026-10-15：逐步向eligible accounts开放，未证明所有地区与账号可用。\n\n许可边界：商业产品条款。采用前按实际使用方式核验组件、云服务与模型条款。\n\n## 证据范围与未知\n\n官方Meet dots和Tasks and memory可核；产品使用合同与开发者接口分别判断。\n\n未公开或仍需目标环境验证的部分：内部调度和memory数据库；原始system prompt；第三方嵌入范围。本页不以产品表面行为推断其隐藏实现。\n\n[OpenAI：Meet dots](https://learn.chatgpt.com/docs/dots)；[OpenAI dots：Tasks and memory](https://learn.chatgpt.com/docs/dots/tasks-and-memory)。",
      "blueprint": {
        "inputs": [
          "持续用户目标与优先级",
          "单独授权的连接",
          "可独立委派的任务"
        ],
        "steps": [
          "以稳定身份协调",
          "分配必要任务context",
          "跟踪后台工作与产物",
          "按权限反馈和调整"
        ],
        "outputs": [
          "独立任务结果",
          "Notes及交互连续性",
          "可调整优先级的协作"
        ]
      },
      "citations": [
        {
          "url": "https://learn.chatgpt.com/docs/dots",
          "label": "OpenAI：Meet dots",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://learn.chatgpt.com/docs/dots/tasks-and-memory",
          "label": "OpenAI dots：Tasks and memory",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": [
        {
          "target": "agent-definition-version",
          "type": "complements",
          "reason": "用Agent定义与版本检查采用时的控制边界；不推断未公开内部机制。"
        },
        {
          "target": "business-task",
          "type": "implements",
          "reason": "公开能力或可见源码体现业务Task的具体产品路线。"
        },
        {
          "target": "child-agent-contract",
          "type": "implements",
          "reason": "公开能力或可见源码体现子Agent委派合同的具体产品路线。"
        },
        {
          "target": "agent-session",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent Session的具体产品路线。"
        },
        {
          "target": "context-assembly",
          "type": "implements",
          "reason": "公开能力或可见源码体现上下文组装的具体产品路线。"
        }
      ],
      "productRoute": {
        "vendor": "OpenAI",
        "category": "持续个人Agent产品",
        "execution": "官方描述云端常驻电脑与浏览器，用户设备离线时可继续。",
        "orchestration": "稳定协调者委派独立后台任务，并跨消息入口延续身份。",
        "context": "官方区分当前context、ChatGPT saved memory和dot notes；委派任务仅获必要上下文。",
        "persistence": "当前context、ChatGPT saved memory和dot notes分开；子任务只获得需要的上下文。",
        "modelBoundary": "官方当前描述使用GPT-6 Astra；不能据此推断用户可替换任意基座。",
        "deployment": "ChatGPT及官方支持渠道；eligible accounts逐步开放。",
        "license": "商业产品条款",
        "availability": "观察于2026-10-15：逐步向eligible accounts开放，未证明所有地区与账号可用。",
        "strengths": "持续身份与任务分离的产品合同值得借鉴；不等于开放runtime。",
        "limits": "待验证或未公开：内部调度和memory数据库；原始system prompt；第三方嵌入范围。公开能力不等同企业负载与领域任务实测。"
      }
    },
    {
      "id": "performance-cache",
      "title": "缓存与依赖失效",
      "en": "Cache Layers",
      "aliases": [],
      "kind": "branch",
      "parentId": "performance",
      "order": 10,
      "summary": "明确复用什么、按什么条件复用，以及何时失效。",
      "question": "怎样把缓存与依赖失效落实为可比较和可验证的工程选择？",
      "body": "前缀缓存复用计算，检索缓存复用候选，工具缓存复用有时效的读结果，答案缓存复用最终内容。越接近业务答案，越需要检查日期、法域、用户和来源。缓存命中不提供额外授权，依赖失效还需覆盖在途context与待发布产物。\n\n[OpenAI：Prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching)；[Claude Code：Prompt caching](https://code.claude.com/docs/en/prompt-caching)。",
      "blueprint": {
        "inputs": [
          "复用对象与依赖",
          "模型和数据合同"
        ],
        "steps": [
          "构造scope和版本键",
          "检查命中资格",
          "传播源及权限变更",
          "测陈旧与隔离错误"
        ],
        "outputs": [
          "有效缓存结果",
          "失效与重建记录"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/prompt-caching",
          "label": "OpenAI：Prompt caching",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://code.claude.com/docs/en/prompt-caching",
          "label": "Claude Code：Prompt caching",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": []
    },
    {
      "id": "prefix-kv-cache",
      "title": "Prompt与KV前缀缓存",
      "en": "Prompt and KV Prefix Cache",
      "aliases": [
        "Prompt Caching",
        "KV Cache"
      ],
      "kind": "concept",
      "parentId": "performance-cache",
      "order": 10,
      "summary": "复用已处理前缀的推理计算，主要影响prefill与输入费用。",
      "question": "怎样设计Prompt与KV前缀缓存，并验证其对任务质量与可靠性的影响？",
      "body": "复用已处理前缀的推理计算，主要影响prefill与输入费用。\n\n前缀缓存复用已经处理过的输入计算，通常降低prefill延迟和输入费用；它不保存可以直接复用的最终答案，也不是跨会话永久memory。自托管推理中的KV复用与厂商API的prompt cache有关联，但生命周期、隔离和计费合同需分别核实。\n\n稳定指令、工具定义和共享材料放在变化较少的位置，动态资料与新交互追加在后，通常有利于前缀匹配。Claude Code官方文档解释其精确前缀行为：前面改动会影响后续复用，换模型、工具或压缩历史也可能重建缓存。不能为了cache hit不断保留无关历史，输入质量与完成条件优先。\n\nOpenAI截至2026-10-15的文档已经区分GPT-5.6及之后模型与更早代际。新一代支持显式breakpoint，缓存写入计费与routing合同也有变化。应用不应沿用“写缓存总是免费”或“cache key必然控制机器路由”的旧假设；按实际模型文档和usage分类核算。\n\n缓存作用于满足条件的前缀，存在最小长度、边界、TTL和服务器容量限制。两个请求看似共享许多文字，并不一定在可查找边界上命中；某次命中也不保证下一次命中。多模型路由、冷启动和会话长时间闲置都要分开测。不要把高命中率直接写成端到端延迟等比例下降，decode与工具时间可能占主导。\n\n企业还要关注租户和用户的cache accounting、敏感前缀探测与保留策略。厂商组织隔离不自动等于应用用户隔离，实际配置要按文档验证。模型换代或compaction后，将重建成本计入预算和SLO。\n\n实验同时报告请求命中、cached read token、write token、普通输入和实际费用，用账单对照。分别测试相同任务连续执行、工具定义变更、模型切换和冷缓存，并用相同业务验收判断优化是否有价值。\n\n**实践重点**：稳定规则和工具前置；按模型核缓存breakpoint、读写费与隔离。\n\n**验证抓手**：测冷/热token、写入、跨模型、compaction与工具变更。\n\n**常见误区**：把缓存视为永久memory，或为了命中保留无关context。\n\n[OpenAI：Prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching)；[Claude Code：Prompt caching](https://code.claude.com/docs/en/prompt-caching)。",
      "blueprint": {
        "inputs": [
          "模型缓存合同",
          "稳定与动态context",
          "实际usage和费用"
        ],
        "steps": [
          "安排稳定前缀",
          "选择支持的缓存边界",
          "按租户和模型核隔离",
          "测冷热及重建成本"
        ],
        "outputs": [
          "缓存读写指标",
          "输入费用明细",
          "延迟和失效边界"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/prompt-caching",
          "label": "OpenAI：Prompt caching",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://code.claude.com/docs/en/prompt-caching",
          "label": "Claude Code：Prompt caching",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "context-assembly",
          "type": "requires",
          "reason": "本节点的设计需要先明确上下文组装。"
        },
        {
          "target": "model-adapter",
          "type": "requires",
          "reason": "本节点的设计需要先明确模型适配层。"
        }
      ]
    },
    {
      "id": "products-harness",
      "title": "代码与文件Harness",
      "en": "Coding and File Harnesses",
      "aliases": [],
      "kind": "branch",
      "parentId": "products",
      "order": 10,
      "summary": "比较完整工具循环、context与执行环境，而非只比较模型。",
      "question": "怎样按技术路线和控制边界比较代码与文件Harness？",
      "body": "这些产品提供面向代码和文件的执行体验，可作为企业受限worker或工程参照。公开许可、源码可见性、发行渠道和预览状态不同。企业业务状态与领域验收宜放在独立控制平面，避免整仓fork后同时承担所有环境和兼容成本。\n\n[OpenAI Codex：固定源码](https://github.com/openai/codex/tree/1ef30bcbe784f1006548adc1542985be32b05109)；[Claude Code：工作原理](https://code.claude.com/docs/en/how-claude-code-works)。",
      "blueprint": {
        "inputs": [
          "文件代码任务",
          "工具及环境约束"
        ],
        "steps": [
          "核验源码和条款",
          "锁定版本渠道",
          "验证取消及恢复",
          "接入自有验收"
        ],
        "outputs": [
          "Harness路线比较",
          "受控worker方案"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/openai/codex/tree/1ef30bcbe784f1006548adc1542985be32b05109",
          "label": "OpenAI Codex：固定源码",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://code.claude.com/docs/en/how-claude-code-works",
          "label": "Claude Code：工作原理",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": []
    },
    {
      "id": "prompt-injection-boundary",
      "title": "提示注入与信任边界",
      "parentId": "security",
      "kind": "concept",
      "order": 10,
      "en": null,
      "aliases": [
        "Prompt injection",
        "越狱",
        "记忆投毒"
      ],
      "summary": "把外部材料作为证据，禁止它提升为操作指令。",
      "question": "网页、文档或记忆中的恶意指令怎样跨层传播？",
      "body": "## 攻击进入哪里\n间接注入藏在检索文档、网页、邮件、工具说明或代码注释里，诱导模型泄漏资料、修改目标或调用危险工具。持久化攻击还可混入摘要和记忆候选，在后续Session重新出现。输入长得像system prompt并不赋予它系统权限。\n\n## 分层防护\n上下文明确标来源、时间与信任等级，外部材料不能直接写入程序性规则。工具能力按当前任务最小化，敏感凭证由网关代持，出网目的地和副作用被独立策略限制。输出验证器检查数据和动作后置条件，不能只问同一个模型“你是否安全”。这些措施降低风险，但没有一个通用字符串过滤器可以证明所有注入都被消除。\n\n## 容易遗漏的传播\n网页摘要可能去掉来源标记；子Agent回报可能把攻击指令包装成“研究建议”；memory合并可能把临时引用固化成偏好。因此来源与信任信息要穿过摘要、委派、记忆和产物，而非仅在最初文档上标一次。对高影响任务，可以要求原文证据和受控重建上下文。\n\n## 测试方法\n组合真实任务、恶意文档、可用工具和跨Session召回，观察是否出现越权动作或外传。同时测合法任务成功与过度拒绝。单轮jailbreak没有成功不代表长期系统安全；红队结果需要绑定模型、harness、工具和策略版本。",
      "blueprint": {
        "inputs": [
          "不可信材料",
          "当前任务权限"
        ],
        "steps": [
          "保留来源标记",
          "限制可执行能力",
          "验证动作和传播"
        ],
        "outputs": [
          "隔离的证据",
          "攻击与误拒指标"
        ]
      },
      "citations": [
        {
          "url": "https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices",
          "label": "MCP：Security best practices",
          "kind": "official-doc"
        },
        {
          "url": "https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents",
          "label": "Anthropic：Effective context engineering",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "context-assembly",
          "type": "controls",
          "reason": "输入组装保留信任与来源分界。"
        },
        {
          "target": "memory",
          "type": "controls",
          "reason": "外部材料不能直接提升为长期规则。"
        },
        {
          "target": "eval-security-redteam",
          "type": "requires",
          "reason": "红队评估攻击成功与合法任务影响。"
        }
      ]
    },
    {
      "id": "reference-architecture",
      "title": "企业 Agent 参考架构",
      "parentId": "foundations",
      "kind": "concept",
      "order": 10,
      "en": null,
      "aliases": [
        "总体蓝图",
        "控制平面",
        "数据平面"
      ],
      "summary": "控制、执行、数据三个平面协作，先保持模块化。",
      "question": "第一版系统怎样组合才容易演进？",
      "body": "## 控制平面\n保存 Agent 定义、发布版本、租户策略、任务、预算与审批。服务端身份决定可见知识和可用工具，prompt 中自报的姓名或 tenant_id 不构成授权。业务 owner 管完成条件，平台维护执行可靠性，数据 owner 管权限和许可。\n\n## 执行平面\n任务 worker 运行 harness；context builder 取规则、任务、证据和记忆；模型适配层调用推理服务；工具网关校验请求并获取回执；verifier 检查产物与业务后置状态。子 Agent 和并发计算是按需增加的能力，不应让每个子系统各自维护一套恢复权威。\n\n## 数据平面\n原件与大产物放对象存储，任务事件、证据元数据和权限放事务数据库，向量与全文索引服务检索，memory 保存跨任务的受控信息。图中的逻辑盒子不要求变成独立微服务。初期可用 API、任务worker、检索worker配托管数据库与对象存储；模块接口隔离优先于进程数量。\n\n## 拆分依据\n检索吞吐、模型配额、CPU计算、长任务资源和高风险工具可能需要独立资源池。先测关键路径和故障传播，再按负载及安全边界拆分。仅凭“未来会很大”提前引入多调度器、多个事实存储，会增加一致性成本。\n\n这是工程建议，不是经过特定企业负载验证的现成SLA。托管harness可减少一部分执行实现，应用仍应拥有任务、授权、证据、业务结果与可迁移导出。",
      "blueprint": {
        "inputs": [
          "任务与身份",
          "发布配置"
        ],
        "steps": [
          "控制平面下发策略",
          "执行平面产生产物",
          "数据平面保存证据"
        ],
        "outputs": [
          "可核查结果",
          "可回放轨迹"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/agents-api/architecture",
          "label": "OpenAI：Agents API architecture",
          "kind": "official-doc"
        },
        {
          "url": "https://www.anthropic.com/engineering/managed-agents",
          "label": "Anthropic：Managed Agents 架构",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "runtime",
          "type": "requires",
          "reason": "执行平面需要可靠运行时。"
        },
        {
          "target": "knowledge",
          "type": "requires",
          "reason": "数据平面提供可信资料。"
        },
        {
          "target": "evaluation",
          "type": "requires",
          "reason": "完成和发布需要独立验证。"
        }
      ]
    },
    {
      "id": "revocation-lineage",
      "title": "撤权、删除与在途影响",
      "parentId": "security",
      "kind": "concept",
      "order": 10,
      "en": null,
      "aliases": [
        "数据血缘",
        "Lineage",
        "Right to delete",
        "撤权"
      ],
      "summary": "沿来源血缘处理索引、上下文、子任务和待交付产物。",
      "question": "文档已删除，为什么模型仍可能引用它？",
      "body": "## 删除不是一个数据库动作\n原文可能已经派生出片段、embedding、摘要、查询缓存、记忆、评测样本和产物。它也可能已进入运行中的模型上下文与子Agent。删除原件或失效索引不能抹去模型刚刚看到的输入。\n\n建立source_version到chunk、retrieval、context、Run、memory和artifact的血缘。撤权事件携带主体范围、资源版本、原因与生效时间，按风险取消受影响Run、停止子任务、失效候选或重建上下文。高风险交付在发布前再次核对来源资格；不能让旧候选因为“已生成”而继续发布。\n\n## 保留与追责\n用户删除、许可到期、版本替代与法定保留可能采用不同处理。业务状态用tombstone记录撤销事实；敏感payload按保留政策清理，审计保留必要ID和hash。备份恢复必须重新应用删除／撤权日志，避免旧数据复活。训练导出需要独立授权，检索许可不自动赋予训练权。\n\n## 验证\n构造两用户共享与私有文档，在检索后、摘要后、子任务运行中和产物发布前分别撤权。观察候选、日志权限、缓存与后续引用；记录撤权完成SLO及不可立即删除的供应商限制。这是跨组件合同，不能只用向量库delete成功回执证明完成。",
      "blueprint": {
        "inputs": [
          "撤权或删除事件",
          "来源血缘"
        ],
        "steps": [
          "定位派生与在途Run",
          "失效或受控重建",
          "重验待交付产物"
        ],
        "outputs": [
          "撤销回执",
          "残余保留说明"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/your-data",
          "label": "OpenAI：API data controls",
          "kind": "official-doc"
        },
        {
          "url": "https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents",
          "label": "Anthropic：Effective context engineering",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "knowledge",
          "type": "controls",
          "reason": "知识生命周期须传播撤销。"
        },
        {
          "target": "memory",
          "type": "controls",
          "reason": "来源失效影响派生记忆。"
        },
        {
          "target": "eval-memory-lifecycle",
          "type": "requires",
          "reason": "跨会话测试删除与遗忘。"
        }
      ]
    },
    {
      "id": "runtime-harness",
      "title": "Harness与循环",
      "en": "Harness and Loop",
      "aliases": [],
      "kind": "branch",
      "parentId": "runtime",
      "order": 10,
      "summary": "模型的推理需要执行、上下文和停止条件共同支撑。",
      "question": "怎样从Harness与循环进入可实施的设计与验证？",
      "body": "本分支把循环、工作流、规划、压缩、停止和环境放在同一责任图中。它们共同决定模型能够看到什么、可以做什么以及何时结束，但各自不应承担其他模块的全部责任。先按任务建立最小可验证循环，再引入复杂规划或多阶段图；不要因为框架提供某能力就默认启用。\n\n[Codex：turn与step循环源码](https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/turn.rs#L454-L518)；[Anthropic：Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)。",
      "blueprint": {
        "inputs": [
          "业务目标与约束",
          "模型与工具能力"
        ],
        "steps": [
          "选择控制边界",
          "构建反馈循环",
          "验证停止与恢复"
        ],
        "outputs": [
          "局部执行合同",
          "可核验完成候选"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/turn.rs#L454-L518",
          "label": "Codex：turn与step循环源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        },
        {
          "url": "https://www.anthropic.com/engineering/building-effective-agents",
          "label": "Anthropic：Building effective agents",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": []
    },
    {
      "id": "sandbox-credentials",
      "title": "沙箱、出网与凭证代持",
      "parentId": "security",
      "kind": "concept",
      "order": 10,
      "en": null,
      "aliases": [
        "Sandbox",
        "microVM",
        "Vault",
        "容器安全"
      ],
      "summary": "代码执行环境可以重建，凭证和业务权威留在受控服务。",
      "question": "怎样安全运行模型生成的代码？",
      "body": "## 隔离对象\n模型生成代码需要最小文件挂载、独立临时目录、CPU／内存／磁盘配额、超时、出网规则和依赖限制。容器是进程隔离手段，是否需要microVM或托管沙箱由威胁模型决定，不能把“放进Docker”当作完整保证。\n\n生产凭证尽量不进入模型可读文件或生成代码的环境。工具网关或vault代持短期授权，以任务、scope和目的地约束动作；日志脱敏，限制调试权限。MCP连接标准不自动替远端server背书，工具定义变化和安装更新也属于供应链边界。\n\n## 持久与临时分离\n沙箱文件可能包含下载资料、浏览器登录和中间结果。为任务隔离目录和身份，明确复用范围、保留和销毁。必须持久保存的产物、证据引用与事件写到独立存储；恢复时重建环境而非假设原进程还活着。共享浏览器登录意味着共享能力，不能仅靠不同聊天窗口宣称隔离。\n\n## 验证\n用无真实危险数据的样本检查禁止域名、越界文件、资源耗尽、恶意依赖、取消后后台进程与清理。读取产物前检查文件类型、大小、路径穿越和宏／脚本等活动内容。验证通过也只证明已测边界，应记录具体环境和政策版本。",
      "blueprint": {
        "inputs": [
          "代码与文件",
          "受限能力票据"
        ],
        "steps": [
          "创建隔离环境",
          "限制出网与资源",
          "扫描并导出产物"
        ],
        "outputs": [
          "可重建环境",
          "受检产物"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/managed-agents",
          "label": "Anthropic：Managed Agents 架构",
          "kind": "official-doc"
        },
        {
          "url": "https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices",
          "label": "MCP：Security best practices",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "sandbox-lifecycle",
          "type": "controls",
          "reason": "运行时实现沙箱创建与销毁。"
        },
        {
          "target": "tool-contract",
          "type": "complements",
          "reason": "工具合同声明允许动作与输出。"
        }
      ]
    },
    {
      "id": "slo-error-budget",
      "title": "分任务SLO与错误预算",
      "parentId": "operations",
      "kind": "concept",
      "order": 10,
      "en": null,
      "aliases": [
        "SLA",
        "p95",
        "Error budget"
      ],
      "summary": "分别管理服务可用、知识新鲜、权限撤销和结果质量。",
      "question": "一个“99.9%可用”的Agent是否足够可靠？",
      "body": "## 指标不是一个数字\n可用性度量能否接受和处理请求，质量度量能否完成业务任务。知识新鲜度、撤权传播、恢复时间、交付时限和正确性各有目标。长研究任务与短问答不共用延迟阈值；按任务slice和风险定义SLO。\n\n严重越权、重复不可逆操作和伪造关键引证通常是发布硬门禁，不能被其他任务的高平均分抵消。统计上零次观察也不等于零风险；报告样本量、试验条件和置信边界。对外SLA还需区分供应商依赖和企业自身可控部分。\n\n## 错误预算怎样驱动行动\n预算消耗过快时暂停扩张，优先修故障和回归，必要时切换只读降级、排队或人工复核。降级不能悄悄把强证据模式变成无来源回答。供应商故障的回退模型也需满足能力和数据资格，不能仅因可调用就投入高风险任务。\n\n## 验证与演练\n以限流、搜索索引更新失败、worker重启、授权服务迟延和验证器不可用进行演练。检查超时传播、用户状态反馈、是否保留已完成工作与回滚路径。质量门禁和服务错误预算相关但不可互相抵销；分别出报告，定位真正的控制措施。\n\n## 口径与责任\n每个指标明确分母、观察窗口、采样缺失与责任人。用户主动取消、系统超时和未知外部效果分别计数；不要从成功率分母中删除困难任务。告警应指向可执行的恢复手册，并记录何时解除降级。",
      "blueprint": {
        "inputs": [
          "任务分层",
          "历史失败与延迟"
        ],
        "steps": [
          "设定独立SLO",
          "监测错误预算",
          "触发降级与修复"
        ],
        "outputs": [
          "运营行动",
          "风险与质量报告"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc"
        },
        {
          "url": "https://github.com/open-telemetry/semantic-conventions-genai",
          "label": "OpenTelemetry：GenAI semantic conventions",
          "kind": "code"
        }
      ],
      "links": [
        {
          "target": "deadline-propagation",
          "type": "requires",
          "reason": "时限需要端到端传播。"
        },
        {
          "target": "model-failover",
          "type": "controls",
          "reason": "回退必须满足任务与数据约束。"
        },
        {
          "target": "evaluation",
          "type": "complements",
          "reason": "质量门禁与服务SLO共同决定发布。"
        }
      ]
    },
    {
      "id": "task-contract",
      "title": "业务任务合同",
      "parentId": "foundations",
      "kind": "concept",
      "order": 10,
      "en": null,
      "aliases": [
        "验收标准",
        "Task contract"
      ],
      "summary": "将模糊目标转为范围、预算、动作与完成证据。",
      "question": "任务完成到底意味着什么？",
      "body": "## 一份最小可执行合同\n任务至少包含 owner、tenant／project、目标实体、时间范围、允许数据源、交付格式、动作权限、质量门槛、成本和截止时间。缺失条件应显式列为待定项；不能让模型用默认假设悄悄扩大任务。任务不是一条聊天消息，也不是一次模型调用。\n\n以投资研究为例，要求“比较三家公司过去八个可获得季度的现金流质量”，需要明确截至时间、币种、财年、GAAP口径和重述处理。结果应包括可复算表、来源和反证，而不是强制输出买入判断。教育任务要区分当场答对与独立迁移；法律任务要固定法域、matter、合同版本与法律截止日。三个应用分支会分别展开。\n\n## 把完成写成可检查的后置条件\n区分硬约束与软评分：无权数据不得使用、不可执行未授权动作、关键计算必须复算等是门禁；表达清晰、覆盖充分可用分级 rubric。每条门槛指定可观察证据与负责验证的组件。开放任务可以保留 inconclusive，不能把“没有发现错误”自动转为成功。\n\n## 合同变化怎样管理\n任务中途增加对象、改变截止时间或转为外部发送，都产生新合同版本。已有证据、审批和验证报告记录其适用版本；重新检查受影响部分。范围扩展不应重置历史操作身份，否则恢复可能重复提交已生效动作。合同页负责业务语义，Task／Run页负责运行对象，评测合同页负责可重复试验。",
      "blueprint": {
        "inputs": [
          "用户目标",
          "授权范围"
        ],
        "steps": [
          "补齐实体与时间",
          "定义硬约束",
          "绑定验收证据"
        ],
        "outputs": [
          "Task合同版本",
          "完成标准"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/building-effective-agents",
          "label": "Anthropic：Building effective agents",
          "kind": "official-doc"
        },
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "business-task",
          "type": "feeds",
          "reason": "运行时Task承载此业务合同。"
        },
        {
          "target": "eval-case-contract",
          "type": "feeds",
          "reason": "评测用例从任务成功条件派生。"
        },
        {
          "target": "domains",
          "type": "complements",
          "reason": "三个领域展示具体合同。"
        }
      ]
    },
    {
      "id": "tool-contract",
      "title": "工具接口合同",
      "en": "Tool Contract",
      "aliases": [
        "工具设计",
        "Function Calling"
      ],
      "kind": "concept",
      "parentId": "runtime-tools",
      "order": 10,
      "summary": "向模型说明可调用能力，并向执行器提供可校验参数与结果。",
      "question": "怎样把业务能力做成模型可选、执行器可验证的工具？",
      "body": "向模型说明可调用能力，并向执行器提供可校验参数与结果。\n\n工具接口同时服务两个对象：模型需要理解何时调用，执行器需要验证能否执行。好的名字和说明可以减少选错工具，但真实约束必须存在于服务器。接口应明确输入类型、默认值、资源范围、读写性质、超时、错误及结果语义，避免一个万能execute工具承载所有企业能力。\n\n例如证据检索返回source_version、定位、时效和可回查引用；计算工具返回公式、输入、单位、精度和结果；写工具返回operation_id、状态、receipt与后置条件。HTTP 200与业务成功不是同义词。身份、tenant和ACL由运行时注入，不应让模型填一个任意user_id就可以切换主体。\n\n工具说明要帮助模型选择，又避免职责重叠。可将更新拆成prepare与commit，将SQL限制为获准模板或只读执行环境；复杂候选查询经parser、资源允许列表、行数和时间限制处理。JSON schema只能验证形状，不能证明查询安全或金额正确；业务验证仍在执行器。\n\n工具版本是Agent发布的一部分，改变字段含义会影响旧会话与恢复。错误应结构化区分可修复参数、权限拒绝、配额和结果未知，使loop选择合法策略。契约测试覆盖边界值、非英文参数、空结果、重复调用、超时和流中断。最终要证明模型看到的定义与实际执行版本一致，而不是只证明某次函数调用返回了对象。\n\n工具返回最好使用少量稳定状态，例如accepted、succeeded、failed、unknown，并附可检查字段。错误细节对执行器有价值，但敏感堆栈和凭证不能直接显示给业务用户。模型可见错误应足够帮助修复，又不泄漏内部环境；运维保留受限原始日志供授权人员诊断。\n\n领域工具可以隐藏基础设施细节。例如让模型请求受限的指标计算，而非自行选择数据库凭证与任意SQL；这样更容易验证输入口径和输出含义。\n\n**实践重点**：职责不重叠；明确读写、边界、schema、错误、receipt与postcondition。\n\n**验证抓手**：对边界参数、无效值、重复调用和超时做契约测试。\n\n**常见误区**：把任意shell/SQL开放作为所有业务工具的替代。\n\n[Agents SDK：Model接口和call ID约束](https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/models/interface.py#L37-L80)；[Anthropic：Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use)。",
      "blueprint": {
        "inputs": [
          "工具职责与资源范围",
          "参数和结果schema",
          "身份与业务约束"
        ],
        "steps": [
          "定义清晰选择语义",
          "注入服务端身份",
          "校验完整参数",
          "返回结构化效果及证据"
        ],
        "outputs": [
          "版本化工具schema",
          "可解释错误",
          "回执与后置条件"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/models/interface.py#L37-L80",
          "label": "Agents SDK：Model接口和call ID约束",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        },
        {
          "url": "https://www.anthropic.com/engineering/advanced-tool-use",
          "label": "Anthropic：Advanced tool use",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": []
    },
    {
      "id": "eval-deterministic-verifier",
      "title": "确定性验证器与证据回执",
      "aliases": [
        "确定性验证",
        "oracle",
        "receipt"
      ],
      "kind": "concept",
      "parentId": "evaluation-grading",
      "order": 11,
      "summary": "用可执行检查和权威状态验证算式、格式、权限与后置条件，并清晰限定每项检查能证明什么。",
      "question": "哪些结果可以程序验证，怎样生成独立证据回执？",
      "body": "## 让验证落到能检查的边界\n确定性验证器把一个具体断言转换成可执行检查，例如JSON schema、金额复算、权限判定、数据库终态、文件diff和签名回执。它的价值是清楚、便宜且可定位错误，但只能证明被检查条件。文件存在不能证明内容正确，URL可访问不能证明支持某个法律命题，接口接受请求不能证明用户收到结果。\n\n## 先声明验证对象和证据\n每份验证报告绑定task合同版本、产物内容hash、数据与as_of快照、grader版本以及执行身份。验证后若产物或依赖变化，应重新验证，不能沿用旧passed。对写操作查询权威业务系统，对生成内容检查结构、来源和数值；必要时组合语义judge与专业复核，明确各自边界。\n\n## 四种结果比二元开关更诚实\npass表示检查范围内满足条件；fail表示发现违反；inconclusive表示证据或接口不足；error表示验证器自身未成功运行。后两者不能自动通过，可在预算内重试、降级或进入人工队列。任务仍可交付已验证部分，但界面和API应说明剩余缺口，不把运行退出当完整业务成功。\n\n## 验证器也需要被验证\n用已知正确、已知错误、边界和篡改样本测试grader，保护其代码与隐藏oracle不被被测Agent修改。计算检查需覆盖单位和期间而非只比较一个浮点值；状态检查需处理最终一致、重复动作与结果未知。回执保留允许、尝试、执行和确认各阶段，缺少确认也应被记录。运行时验证可驱动修复，离线评测可统计表现，两者共用合同而不混淆作用。\n\n## 验证器本身也要有测试\n准备正确产物、已知错误产物、依赖不可用和证据不足四类样本，检查验证器是否把执行异常误报为通过。算术验证同时检查单位和输入来源；文件验证要打开并解析内容，业务验证要读取权威状态。回执注明规则版本、产物摘要、运行时间、检查范围和证据位置。验证代码由受信侧执行，候选Agent不能改动规则或测试答案；否则通过分数可能只是验证环境被改变。",
      "blueprint": {
        "inputs": [
          "产物hash和合同版本",
          "权威状态或可执行oracle",
          "结构数值及约束规则"
        ],
        "steps": [
          "核验证环境自身有效",
          "检查结构公式与终态",
          "绑定证据到产物和时间",
          "输出四态验证结果"
        ],
        "outputs": [
          "可追溯验证回执",
          "失败位置及未覆盖语义"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc",
          "note": "2026-01-09；官方方法背景，具体合同与阈值须按业务验证。"
        }
      ],
      "links": [],
      "en": "Deterministic Verifier"
    },
    {
      "id": "learning-feedback-flywheel",
      "title": "Trace到能力改进的闭环",
      "aliases": [
        "反馈闭环",
        "持续改进",
        "能力积累"
      ],
      "kind": "concept",
      "parentId": "learning-improvement",
      "order": 11,
      "summary": "将运行证据、专家反馈、失败分类、评测、候选改变和发布连接起来，避免只积累原始聊天。",
      "question": "怎样把真实失败转成新用例、候选改动和受控能力增长？",
      "body": "## 将反馈连接成可执行改变\n闭环从生产trace与用户反馈出发，经过用途与隐私处理、重放、根因分类、新case和金标、候选改变、离线持出、专家抽审、shadow、canary，最后晋升或回滚。日志记录发生了什么，专家解释哪些差异影响业务，评测把这些判断变成可重复标准；三者缺一，反馈容易停留在评论里。\n\n## 不把所有问题交给Prompt\n证据缺失修接入和检索，参数不清修工具，跨session遗忘修日志与memory，顺序和授权问题修workflow与policy。有充分证据仍稳定推理错误时，再比较prompt、skill、模型或权重训练。自动分类只是候选诊断，重要根因应附证据和人工确认；同一失败可以有主次因素。\n\n## 自适应有不同机制\nACE一类研究更新context playbook，memory整理更新外部状态；SFT或SEAL类路线才涉及权重改变。这些论文实验或公开示例的结果不能证明任意企业任务自动获益。每种改变明确输入、作用域、成本、适用范围和回滚方式，并通过未参与优化的新任务判断效果。持续保存原始聊天也可能持续累积错误。\n\n## 控制自动化的最后一步\n优化器可以提diff、生成用例或建议rubric，但不应独自掌握隐藏test、reward、生产权限和晋升指针。保留独立持出，校准judge，避免自己出题自己改卷的闭环。以每成功任务成本、严重错误、审阅时间和业务目标观察复利，允许停止没有净收益的改进。OpenAI公开improvement loop展示了trace到变更建议的连接方式，其演示不替代自有任务的验证。",
      "blueprint": {
        "inputs": [
          "trace和用户反馈",
          "专家修订及失败分类",
          "能力与发布版本"
        ],
        "steps": [
          "去噪确认业务问题",
          "新增case和独立评分",
          "按根因生成最小改动",
          "持出验证晋升再观察"
        ],
        "outputs": [
          "新能力或否决候选",
          "反馈到发布的证据链"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/cookbook/examples/agents_sdk/agent_improvement_loop",
          "label": "Trace到能力改进的闭环：原始文档",
          "kind": "official-doc"
        },
        {
          "url": "https://arxiv.org/abs/2510.04618",
          "label": "Trace到能力改进的闭环：原始文档",
          "kind": "paper"
        },
        {
          "url": "https://arxiv.org/abs/2506.10943",
          "label": "Trace到能力改进的闭环：原始文档",
          "kind": "paper"
        }
      ],
      "links": [
        {
          "target": "learning-method-selection",
          "type": "requires",
          "reason": "反馈先归因再变更。"
        },
        {
          "target": "learning-skill-promotion",
          "type": "feeds",
          "reason": "经验证的方法进入候选能力目录。"
        }
      ],
      "en": "Feedback Flywheel"
    },
    {
      "id": "eval-llm-judge",
      "title": "LLM Judge与语义Rubric",
      "aliases": [
        "语义评分",
        "rubric",
        "pairwise"
      ],
      "kind": "concept",
      "parentId": "evaluation-grading",
      "order": 12,
      "summary": "用任务、证据和明确rubric评估蕴涵、覆盖与解释质量，保留无法判定并控制风格偏差。",
      "question": "如何让模型评分可校准、可追证据且不掩盖硬错误？",
      "body": "## 语义判断需要任务和证据\nLLM judge适合评价总结覆盖、引用蕴涵、解释清楚程度、合同风险分析和教学方法。给它原任务、可见证据、候选产物与具体rubric，而不是只给答案让它凭常识裁判。将每项评分与证据片段相连，并允许无法判定；对于新近事实或专业规则，judge同样可能不知道或记错。\n\n## 选择合适的评分形状\nreference-based适合有可接受答案范围的任务；pairwise适合比较两个开放产物；rubric适合分开衡量不同要求。标明严重错误、必要覆盖、允许变化与反例，避免“很好、一般、不好”的模糊等级。确定性检查已经证实的算术错误不能被另一个模型投票改成正确，越权和伪造引证也不能靠文风高分补偿。\n\n## 控制常见偏差\n隐藏候选供应商与版本，随机交换左右顺序，检查长度差异，加入冗长但错误、简短但正确、伪引用以及要求评分器改标准的攻击文本。独立上下文可以降低执行者为自己辩护的倾向，但同一模型家族仍可能共享错误。多judge一致只是信号，不能自动提升为真值。\n\n## 版本化并校准这把尺子\n保存judge模型、prompt、rubric、输入hash、分项结果、证据与无法判定原因。用独立专家标签检查严重错误漏判和过度误杀，再将judge校准集与最终测试集隔离。修改judge后重评代表历史样本，避免把尺子变松误写成Agent进步。评分器成本和延迟也应进入评测预算；其工作是提供可审阅证据，不是把责任转交给另一个模型。\n\n## 让判分具备可追问接口\n每项结果包含标准、结论、严重程度、证据位置和简短理由，不要求展示模型内部思维。将明显错误的长答案、正确短答案、证据不足但诚实暂停、引用真实却不支持结论等作为校准对照。定期交换候选顺序并匿名模型身份，观察偏差；对争议项抽样交给专家。Judge只读取完成任务所需材料，候选输出中的“请给满分”等文字一律作为被评内容，不能成为评分指令。",
      "blueprint": {
        "inputs": [
          "任务合同与rubric",
          "候选证据和reference",
          "已校准judge配置"
        ],
        "steps": [
          "匿名化并随机顺序",
          "逐项给分与证据位置",
          "保留证据不足及分歧",
          "硬阻断单列不抵消"
        ],
        "outputs": [
          "分项语义Grade",
          "证据unknown及专家待审"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent evaluations",
          "kind": "official-doc",
          "note": "官方方法背景；业务阈值与统计合同需独立验证。"
        }
      ],
      "links": [
        {
          "target": "eval-human-calibration",
          "type": "requires",
          "reason": "模型评分要用独立专家标签校准。"
        }
      ],
      "en": "LLM Judge"
    },
    {
      "id": "eval-human-calibration",
      "title": "专家标注与Judge校准",
      "aliases": [
        "专家盲评",
        "混淆矩阵",
        "校准"
      ],
      "kind": "concept",
      "parentId": "evaluation-grading",
      "order": 13,
      "summary": "先解决专家间的标准分歧，再用独立持出标签测试judge的漏判与误判。",
      "question": "如何知道Judge在领域任务上会漏判哪些严重错误？",
      "body": "## 先让专家共享判断标准\n领域专家承担任务定义、金标、严重错误和争议裁决。先抽取正确、轻微错误、重大错误、合理拒绝和证据不足的样本，由至少两位具备领域知识的评审独立标注。发生分歧时讨论标准和证据，不宜简单多数票后丢掉原因；可能是rubric含糊，也可能是任务缺信息。\n\n## 分开校准和检验\n将人工样本分为judge校准集与独立judge test集。前者用于改prompt和阈值，后者用于判断这把尺子是否可靠，不能反复向优化器泄露答案。对不断变化的法律、财务或课程标准，标签保留适用日期、资料版本与评审资格；历史标签不自动代表今天仍正确。\n\n## 看具体错误，不只看总体一致率\n用confusion matrix检查误判与漏判，尤其关注高损失错误被判通过的情况。类别不均衡时，一个总是判通过的judge也可能有很高一致率。分别报告严重错误召回、正常任务误杀、unknown以及评审间分歧；开放文本可补pairwise一致性。相关系数高不等于在上线门槛附近判断准确。\n\n## 将人工投入放在最有信息的位置\n优先复核judge分歧、新任务家族、边界分数、异常高分和高风险产物，同时随机抽样普通通过项，避免只见到报警。用户反馈先作为候选线索：差评可能是不满意正确结论，点赞可能来自流畅表达。每次变更grader或产品合同都重新校准代表集。专家分钟数是系统成本的一部分，应与任务成功和错误损失一起度量，而不是假设所有人工都能被自动评分消除。\n\n## 优先检查高代价错漏判\n假设Judge把正确草稿错判为不合格，会增加人工工作；把带伪造法律引证的草稿判合格，可能造成更高损失。二者分别统计并按领域设置门槛，不能只报总体一致率。专家也可能有分歧，保留原标签、理由和裁决规则，而非自动把多数票当真值。校准后冻结配置，在未参与调整的样本上评估；需要升级rubric时建立新版本，避免历史成绩悄悄改变含义。",
      "blueprint": {
        "inputs": [
          "专家盲评样本",
          "rubric和严重错误标准",
          "候选judge版本"
        ],
        "steps": [
          "双人标注裁决分歧",
          "拆分校准及judge test",
          "核混淆矩阵和严重漏判",
          "换judge重跑可比历史"
        ],
        "outputs": [
          "校准阈值及误差",
          "审阅队列与适用范围"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent evaluations",
          "kind": "official-doc",
          "note": "官方方法背景；业务阈值与统计合同需独立验证。"
        }
      ],
      "links": [],
      "en": "Judge Calibration"
    },
    {
      "id": "eval-pass-metrics",
      "title": "pass@k与pass^k",
      "aliases": [
        "pass@k",
        "pass^k",
        "重复可靠性"
      ],
      "kind": "concept",
      "parentId": "evaluation-statistics",
      "order": 14,
      "summary": "区分多次尝试至少一次成功和每次都成功，解释可靠性与候选选择机制的关系。",
      "question": "至少成功一次与每次都成功，为何相差很大？",
      "body": "## 至少成功一次和始终成功\npass@k表示同一任务在k次尝试中至少有一次成功；pass^k表示k次尝试全部成功。前者适合能生成多个候选并可靠选出正确结果的产品，后者更接近反复面对相似用户需求时的稳定性。Sierra的τ-bench研究采用状态终态和重复成功来观察这类可靠性，但其模拟环境成绩不能直接换算为企业生产成功率。\n\n## 公式的前提必须一起给出\n若同一任务每次独立且成功概率p不变，则pass@k=1−(1−p)^k，pass^k=p^k。p为0.8、k为5时，两者分别为99.968%和32.768%。这不是矛盾，而是回答不同问题。真实任务难度不同，失败还可能相关，应逐case进行多次trial再聚合，不能将全部任务平均成功率直接代入公式。\n\n## 候选选择器决定实际价值\n即使五次尝试中有一次正确，系统若无法识别它，用户仍可能拿到错误结果。应把生成、验证、选择和交付整条链纳入评测，统计选择器误判以及额外时间和费用。对于有副作用的操作，也不能为了提高pass@k重复执行五次发送或下单；需要隔离候选与真正提交。\n\n## 报告可比的尝试预算\n同时给pass@1、k值、每case trial数、采样设置、时间和工具预算、验证方式与置信区间。重试已经包含在一次trial内部时，不能又把每个内部步骤当成独立尝试。比较模型应统一预算或展示质量成本曲线，避免通过增加尝试次数制造能力领先。对要求一致可靠的场景，不以接近百分之百的pass@k掩盖较低单次成功率。\n\n## 区分理论概率与实测估计\n公式需要独立同概率假设，实际报告应以逐任务试验为依据，并说明如何从有限样本估计。某任务可能一直失败，另一任务几乎总成功；把二者平均后套幂次会高估或低估稳定性。用户可接受重试时，也应计算端到端预算内完成率，而不是无限尝试上限。必须提交一次真实动作的场景，先在隔离环境生成候选，再由可靠规则选择，最终提交的成功率单独统计。",
      "blueprint": {
        "inputs": [
          "逐case重复结果",
          "k值及统一尝试预算",
          "选择器与副作用合同"
        ],
        "steps": [
          "区分至少一次和全成功",
          "核独立性及失败相关",
          "逐case估计再聚合",
          "计选择器费用和交付"
        ],
        "outputs": [
          "pass@1、pass@k、pass^k",
          "预算区间及相关性说明"
        ]
      },
      "citations": [
        {
          "url": "https://sierra.ai/blog/benchmarking-ai-agents",
          "label": "Sierra：τ-bench与重复可靠性",
          "kind": "official-doc",
          "note": "2024研究；模拟用户与状态评分不能替代生产效果。"
        }
      ],
      "links": [
        {
          "target": "eval-trial-replay",
          "type": "requires",
          "reason": "重复试验应从声明的独立初态开始。"
        }
      ],
      "en": "Repeated Reliability"
    },
    {
      "id": "eval-statistical-confidence",
      "title": "置信区间、配对比较与稀有风险",
      "aliases": [
        "Wilson",
        "bootstrap",
        "置信区间"
      ],
      "kind": "concept",
      "parentId": "evaluation-statistics",
      "order": 15,
      "summary": "用不确定性、配对实验与预设停止规则约束百分点提升和零失败声明。",
      "question": "分数提升是否可信，零次严重错误能说明什么？",
      "body": "## 一个百分点不是精确真相\n有限样本、模型随机性、任务难度与基础设施噪声都会影响分数。100个独立case中90个成功，Wilson 95%区间约82.6%至94.5%；在这个规模上从90%到92%并不自动构成稳定提升。报告点估计、样本数、区间和任务切片，避免只给一位小数的排行榜。\n\n## 使用配对和合适的实验单位\n比较两个版本时尽量使用相同case及相同资源。以任务或用户为cluster进行配对bootstrap，保留同一任务多次trial的相关性；不能把一个用户的十个相近session当十个独立用户。领域风险差异较大时分别给结果，必要时根据目标生产分布加权，并公开权重与分母。\n\n## 零失败仍有上界\n在独立同分布近似下，n次零失败的95%上界约为3/n。要使上界约0.1%，需要约3000次独立观察；零事件不能证明绝对安全。真实攻击、数据与用户行为会变化，因此该估计仅约束被观察分布，不能保证未来所有情形。严重错误还需要压力测试、设计防线与持续监测。\n\n## 在看结果前写实验规则\n事先规定主要指标、最小可接受差异、不能退化切片、成本延迟约束、样本预算和停止条件。反复比较许多prompt再只汇报最佳者，会产生选择偏差；多次偷看小流量并提前停测也会夸大收益。使用预设样本量或合适的顺序方法，并保留所有候选记录。统计判断支持决策，不替代领域损失和上线责任的讨论。\n\n将这些检查固定在版本化测试集中，并同时观察通过项与失败项，才能区分真实能力变化与评分尺度变化。\n\n## 把业务门槛转成实验设计\n先估计基线和最小有意义提升，再据预期方差决定样本预算；不同任务的损失可单列严重事件门槛，而非混成加权平均。对同批任务比较两个版本，可报告一方通过另一方失败的配对数量，辅助理解净变化来自哪里。发现某切片显著退化后，应先分析原因，再设计新的验证，不能反复删样本直到总体分数好看。上线观察与离线实验分别保留分布和版本信息。",
      "blueprint": {
        "inputs": [
          "配对版本逐case结果",
          "任务或用户cluster",
          "预设指标与停止规则"
        ],
        "steps": [
          "算点估计和区间",
          "按相关单位配对bootstrap",
          "评严重事件上界及效应量",
          "处理多重比较和顺序观察"
        ],
        "outputs": [
          "差异区间及不确定性",
          "样本充分性和晋升依据"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent evaluations",
          "kind": "official-doc",
          "note": "官方方法背景；业务阈值与统计合同需独立验证。"
        }
      ],
      "links": [
        {
          "target": "eval-pass-metrics",
          "type": "complements",
          "reason": "指标需要估计不确定性及相关性。"
        }
      ],
      "en": "Statistical Confidence"
    },
    {
      "id": "eval-holdout-contamination",
      "title": "持出集、时序划分与污染控制",
      "aliases": [
        "持出集",
        "污染",
        "时间切分"
      ],
      "kind": "concept",
      "parentId": "evaluation-statistics",
      "order": 16,
      "summary": "将开发、选型、最终测试和fresh audit分开，控制近重复、历史残留与参数知识中的未来泄漏。",
      "question": "怎样避免训练、反复调参和未来信息污染泛化证据？",
      "body": "## 不同数据集承担不同职责\ndev用于改prompt、工具和skill；validation用于选版本；锁定test提供最终泛化证据；fresh audit持续加入从未暴露的新任务。公开回归集可以帮助稳定承诺，但优化器反复看过它之后，就不能继续当成未见测试。记录每个case向哪些人、模型或优化流程暴露过。\n\n## 按真实关联关系划分\n同一报告的相邻段落、同一合同的红线与原版、同一学生的近似session和相同题型模板，不能轻率地随机分到两边。按文档、公司、客户matter、用户、组织或题型家族group split，再按时间保留新样本。合成改写也可能仍是近重复；去重不能只比较字符串hash。\n\n## 清理污染，但保留case初态\n每个trial恢复声明快照，清除其他trial残留的答案、文件、数据库修改、memory和git历史。长期记忆与warm-cache测试保留明确预置的状态，并单独报告。被测Agent不能读隐藏答案或改grader。共享基础设施资源还可能产生相关失败，应作为实验条件记录，而不是一律删除失败行。\n\n## 时间截止也约束不了全部参数知识\n金融历史任务即使只提供某个决策日之前的资料，较晚训练的基础模型也可能知道随后结果。资料as_of不是完全消除未来泄漏的证明。历史评测更适合检验取证、计算与约束遵从；投资预测收益优先用冻结候选之后的前瞻任务衡量。法律和教育同样要防新版本答案、题库和专家反馈进入测试链，避免“自我改进”其实是背住了验收样本。\n\n## 看不到答案仍可能知道未来\n历史投资案例即使工具只返回当时资料，基座权重仍可能记得之后的财报或股价。可使用真正前瞻窗口、训练截止后新事件或精心设计的替代任务，但都应声明适用限制。对法律与教育，按案件或题型家族分组，防止只换名字和数字就落到另一集合。优化人员不能读取隐藏答案；将测试错误全文直接喂回修复器，会把test变成开发集，需要另建独立审计。",
      "blueprint": {
        "inputs": [
          "来源实体及可得时间",
          "训练开发与回归数据",
          "隐藏grader和初态"
        ],
        "steps": [
          "按关联组及时间切分",
          "去改写和题型近重复",
          "隔离test答案与grader",
          "以fresh audit核参数泄漏"
        ],
        "outputs": [
          "数据分区及污染审计",
          "可支持的泛化声明"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent evaluations",
          "kind": "official-doc",
          "note": "官方方法背景；业务阈值与统计合同需独立验证。"
        }
      ],
      "links": [
        {
          "target": "eval-dataset-curation",
          "type": "controls",
          "reason": "分组、去重与隔离控制泛化证据。"
        }
      ],
      "en": "Holdout Integrity"
    },
    {
      "id": "eval-model-migration",
      "title": "模型升级与Harness交互评测",
      "aliases": [
        "模型升级",
        "四格实验",
        "消融"
      ],
      "kind": "concept",
      "parentId": "evaluation-release",
      "order": 17,
      "summary": "通过旧新模型与旧新harness对照，判断提升来自模型、适配还是两者交互。",
      "question": "换模型时怎样区分模型收益、适配收益和交互退化？",
      "body": "## 升级的是整个Agent组合\n模型更强不保证原Agent更强。工具协议、消息优先级、reasoning状态、缓存、上下文和拒答行为都会改变。建立旧模型加旧harness、新模型加旧harness、旧模型加新harness、新模型加新harness四格对照，分别判断兼容性、适配收益与交互效应。若只有改prompt后变好，应报告组合提升而非全部归功于模型。\n\n## 建立领域能力矩阵\n覆盖结构化输出、并行工具、表格与长文档、中文术语、证据推理、memory、权限、长任务停止和成本延迟。记录上下文和输出上限及不支持特性，adapter遇到unsupported应显式返回，不静默抹去参数。固定同一业务用例、数据和预算，先看严重错误与基本回归，再看新能力机会。\n\n## 对旧补丁做消融\n频繁context reset、冗余自评、固定工具顺序或过短计划，可能是旧模型的必要补救，也可能限制新模型。给补丁记录适用版本、失败依据和删除条件；在相同条件下比较保留与移除，而不是把所有历史指令永久累积。模型接口兼容也不意味着语义行为兼容。\n\n## 从离线资格走到受控上线\n通过完整harness、持出与专家抽审后，才进入shadow和canary。release manifest冻结provider、model snapshot、prompt、工具、workflow、memory策略和验证器；每个run另记动态数据与授权。供应商不提供固定snapshot时，明确复现限制并持续跑sentinel cases。回滚也回滚组合配置，同时处理新版本已经写入的memory和业务状态。\n\n## 为不可重复部分设计报警\n接口允许固定snapshot时记录精确标识，不只存家族名；无法固定时保留每次请求的服务端模型信息和观察日期。为关键工具、中文否定、引用、拒绝和长任务恢复选少量sentinel，按节奏运行并监测突变。报警触发完整回归和抽审，不直接把一次波动当成供应商升级。跨provider迁移尤其要重建消息、工具结果和授权上下文，旧服务的私有状态标识不能假定可直接复用。",
      "blueprint": {
        "inputs": [
          "旧新模型和harness",
          "能力矩阵及持出",
          "同数据权限及预算"
        ],
        "steps": [
          "执行四格对照",
          "核协议及unsupported",
          "消融历史workaround",
          "过严重错误及产品门禁"
        ],
        "outputs": [
          "组合升级资格证据",
          "兼容限制及sentinel"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/cookbook/examples/agents_sdk/agent_improvement_loop",
          "label": "OpenAI：Agent improvement loop",
          "kind": "official-doc",
          "note": "公开示例；本页发布合同为工程设计建议。"
        }
      ],
      "links": [
        {
          "target": "eval-harness-fidelity",
          "type": "requires",
          "reason": "升级资格不能只用小型工具循环证明。"
        },
        {
          "target": "eval-holdout-contamination",
          "type": "requires",
          "reason": "适配后要验证未见任务。"
        },
        {
          "target": "model-upgrade-matrix",
          "type": "complements",
          "reason": "运行时实现升级矩阵，评测层提供资格证据。"
        },
        {
          "target": "model-adapter",
          "type": "verifies",
          "reason": "检验协议适配后的真实任务表现。"
        }
      ],
      "en": "Model Migration Evaluation"
    },
    {
      "id": "eval-model-routing",
      "title": "模型Router与Failover评测",
      "aliases": [
        "模型路由",
        "failover",
        "降级"
      ],
      "kind": "concept",
      "parentId": "evaluation-release",
      "order": 18,
      "summary": "把路由看作独立决策系统，检查困难或高风险任务漏判、合格备援和端到端成本。",
      "question": "怎样验证每种任务被交给合格模型，并安全故障切换？",
      "body": "## Router本身会犯错\n路由不只是省token的规则，它决定哪种任务交给哪个能力组合。输入可包括风险、复杂度、上下文、数据资格、deadline和成本。先建立可解释的确定性路由，再按真实证据决定是否训练router。把困难金融问题误分给便宜模型，是决策错误，不能在统计时剔除后宣称小模型成功率很高。\n\n## 先给每个候选模型取得资格\n按任务家族测试格式、工具、拒答、证据、权限和延迟；高风险任务设可路由模型允许列表。供应商故障时，备选必须有权处理同类数据并满足必要验证。若没有合格替代，返回有标记的降级结果、排队或升级人工；不能为了保持“可用”静默转到未经批准的端点。\n\n## 评价选择和整体链路\n单独测高风险识别漏判、复杂度分类、路由稳定性和fallback触发，再测端到端任务成功、严重错误与每成功任务成本。比较oracle路由、固定单模型和实际router，量化选择损失。切片保留任务难度和流量分布，不把便宜模型承担的简单样本与高档模型困难样本直接横比。\n\n## 换模型时显式恢复状态\n中途failover要用已提交任务状态、证据、工具回执和剩余预算重建上下文，不假设供应商共享隐式推理或工具ID。对尚未确认的写操作先查终态，避免新模型重复提交。路由策略、阈值和候选资格都进入release manifest；模型、价格或配额变化后重新测量。收益应体现在有效成本与风险约束，而不是单看便宜模型调用占比。\n\n## 评估选择器本身的错误\n按任务难度、领域、长度和风险分别给路由混淆情况。将高风险法律任务误送到未获资格的小模型，与把简单抽取送到昂贵模型，是不同损失。故障注入覆盖限流、超时、截断和工具协议不兼容，检查切换后是否丢引用或重复动作。为每条备援路径设置预算和停止条件，若没有合格模型则显式暂停。不能用便宜模型的大量简单任务掩盖难题分支的严重失败。",
      "blueprint": {
        "inputs": [
          "任务切片与路由策略",
          "各模型能力资格",
          "故障及fallback预算"
        ],
        "steps": [
          "评路由误分和难题",
          "核备援数据权限",
          "注入故障重建必要状态",
          "比质量尾延迟总费"
        ],
        "outputs": [
          "路由及fallback成功率",
          "降级边界和禁路由任务"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/cookbook/examples/agents_sdk/agent_improvement_loop",
          "label": "OpenAI：Agent improvement loop",
          "kind": "official-doc",
          "note": "公开示例；本页发布合同为工程设计建议。"
        }
      ],
      "links": [
        {
          "target": "eval-model-migration",
          "type": "requires",
          "reason": "每个可路由或备援模型先取得任务资格。"
        }
      ],
      "en": "Routing Evaluation"
    },
    {
      "id": "eval-shadow",
      "title": "Shadow运行与无副作用比较",
      "aliases": [
        "影子流量",
        "镜像",
        "隔离"
      ],
      "kind": "concept",
      "parentId": "evaluation-release",
      "order": 19,
      "summary": "在脱敏真实流量上运行候选，禁止真实写动作，观察分布、检索、质量与性能代理信号。",
      "question": "如何在真实任务分布上比较候选，又不产生业务副作用？",
      "body": "## 在真实分布上旁路观察\nShadow将有使用资格的生产事件复制给候选Agent，使其经历更真实的数据格式、长尾问题和依赖延迟。它适合在不改变用户结果的前提下比较取证、调用、产物和费用。复制前核用途、权限、保留和去标识，候选应取得与原请求一致且不扩大的数据scope。\n\n## 写操作必须隔离\n禁用真实发送、购买、删除和业务更新，把候选写动作送到模拟器、快照或独立测试租户。仅在prompt里写“不要真正执行”不是可靠隔离。保留拟执行参数、权限决策和可验证的模拟终态，以便发现危险动作；不要把因为写工具完全不可用而失败的结果，与真实版本不加说明地比较。\n\n## 保持可比，也暴露分布差距\n对同一事件关联control和candidate trace，记录模型、数据快照、工具、memory初态、资源、时间与成本。真实流量可能包含离线集没有的用户简称、跨设备上下文、权限边界和冷启动；将这些差距转为新case。候选不能把shadow得到的私人memory写回生产，避免改变后续control行为。\n\n## 明确能回答和不能回答的问题\nShadow可以发现质量、检索与性能代理指标，却不能直接证明学生学习提升、投资收益或真实外部动作的履行效果。也不能替代canary下的用户行为与交付验证。预设观察窗口、严重错误门槛和进入下一阶段的条件；样本不足时保留不确定性。输出应包含差异、证据、失败分布和剩余风险，而非一个笼统“影子测试已通过”。\n\n## 影子状态需要独立生命周期\n候选运行使用隔离数据库或受控快照，写入记忆、发送邮件和生成外部订单等都必须被阻断或替换。即便工具名称标为只读，也要核实服务实际是否修改访问状态或触发回调。保存候选应当提交的意图，与正式版本的真实结果比较，但不把模拟成功写成真实履约。影子样本也可能包含私人数据，应继承原访问与保留资格；其结论是发现分布差距，而非证明生产干预带来的因果收益。",
      "blueprint": {
        "inputs": [
          "生产任务授权副本",
          "隔离候选release",
          "只读或模拟写工具"
        ],
        "steps": [
          "脱敏复制输入分布",
          "阻断真实业务提交",
          "比终态错误和资源",
          "定位离线覆盖缺口"
        ],
        "outputs": [
          "真实分布比较报告",
          "灰度前缺口与新增case"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent evaluations",
          "kind": "official-doc",
          "note": "官方方法背景；业务阈值与统计合同需独立验证。"
        }
      ],
      "links": [
        {
          "target": "eval-harness-fidelity",
          "type": "complements",
          "reason": "观察真实分布和产品边界。"
        }
      ],
      "en": "Shadow Evaluation"
    },
    {
      "id": "agent-loop",
      "title": "Agent执行循环",
      "en": "Agent Loop",
      "aliases": [
        "ReAct循环",
        "代理循环"
      ],
      "kind": "concept",
      "parentId": "runtime-harness",
      "order": 20,
      "summary": "重复进行观察、行动、反馈与状态更新的执行过程。",
      "question": "怎样让模型行动循环支持插话、取消和可解释恢复？",
      "body": "重复进行观察、行动、反馈与状态更新的执行过程。\n\n一轮交互并不等于一次模型请求。用户可能在Agent搜索期间补充限制；模型可能一次请求多个工具，再根据结果继续推理；一次业务任务也可能经过多个交互turn。将Session、Turn、Step和ModelCall分开记录，才能解释一次操作为什么发生，以及哪个输入在当时有效。\n\nCodex固定源码的run_turn在step边界消费待处理输入，执行hooks，并捕获该步的上下文。注释强调，context、模型可见工具和实际调用需要共享同一份请求视图。这避免模型按照旧工具定义作出决定，执行器却按新定义解释参数。该源码说明了公开CLI的设计，不能据此断言所有桌面或托管版本完全相同。\n\n推荐的循环先读取已提交状态和新输入，再组装当前上下文；模型请求完成解析后，验证每个完整工具调用；对写操作预先持久化操作身份与意图，再交网关执行；工具回执和错误落盘后，才判断继续、等待或输出候选。流式文字可以先展示，但不能把半个JSON对象当可执行命令。取消和用户纠正应有明确入口，而非任意线程直接修改messages数组。\n\n停止也是循环的一部分。最终输出、预算耗尽、权限不足、用户取消和结果未知是不同状态。模型没有再请求工具不一定代表工作完成，工具失败也不一定应该立即重试。测试应覆盖多工具并发、工具结果缺失、断流、插话和完成前取消，并检查持久事件能否解释每次状态转换。\n\n例如用户先要求比较三家公司，Agent运行中又补充“只用截止昨日可见资料”。这条补充应在下一个step进入权威任务限制，并使已取得的不合格资料退出候选。若后台子Agent仍按旧截止日工作，父loop必须识别其产物版本，不能直接混入最后报告。这样的测试比只检查循环能跑十轮更接近企业需求。\n\n**实践重点**：按turn与step消费输入；记录每次模型和工具结果，再决定继续、等待或完成。\n\n**验证抓手**：检验工具失败、用户插话、预算耗尽及无工具最终输出。\n\n**常见误区**：只写while直到模型说完成，没有预算、取消和恢复。\n\n[Codex：turn与step循环源码](https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/turn.rs#L454-L518)；[Claude Code：工作原理](https://code.claude.com/docs/en/how-claude-code-works)。",
      "blueprint": {
        "inputs": [
          "已提交Run状态",
          "待处理用户输入",
          "本步能力与预算"
        ],
        "steps": [
          "在step边界消费输入",
          "冻结本步上下文和工具视图",
          "解析完整调用并执行",
          "提交结果后判定下一状态"
        ],
        "outputs": [
          "有序Step事件",
          "工具调用与回执",
          "继续、等待或完成候选"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/turn.rs#L454-L518",
          "label": "Codex：turn与step循环源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        },
        {
          "url": "https://code.claude.com/docs/en/how-claude-code-works",
          "label": "Claude Code：工作原理",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": [
        {
          "target": "agent-harness",
          "type": "requires",
          "reason": "本节点的设计需要先明确Agent Harness。"
        }
      ]
    },
    {
      "id": "agent-session",
      "title": "Agent Session",
      "en": "Agent Session",
      "aliases": [
        "会话",
        "Thread"
      ],
      "kind": "concept",
      "parentId": "runtime-task-session",
      "order": 20,
      "summary": "持续交互与事件的容器，独立于当前context窗口。",
      "question": "会话、模型窗口、后台Task和长期记忆应怎样分开？",
      "body": "持续交互与事件的容器，独立于当前context窗口。\n\nSession是持续交互和事件的容器，与当前模型窗口、业务Task和沙箱都不同。一段会话可以讨论多个任务；同一Task也可能由另一个已授权会话继续。新窗口未必意味着新Session，而新的Session也不自动获得用户全部历史。数据模型应保存这些映射，而不是靠聊天标题猜测归属。\n\nClaude Code官方文档描述本地JSONL记录、同ID恢复和新ID分叉；OpenAI Agents SDK的Session协议提供历史读取、追加、弹出与清空。它们说明会话连续性可以被持久化，但这种history接口本身没有完成企业长期记忆的来源、冲突、TTL与删除传播治理。\n\n会话合同应记录租户、参与者、项目、可见范围、事件游标、保留策略和当前执行关联。Resume延续同一历史；fork复制某个边界的历史到新身份，并应重新检查工具和资料权限。多设备并发输入需要排序，不能两个客户端各自覆盖messages。模型窗口只是从Session中选择出来的当前视图。\n\n关闭会话、取消后台任务、删除聊天和撤回记忆是四种产品操作。关闭窗口不应悄悄终止获准后台任务；删除聊天也不必然删除合规要求保留的业务记录。界面需清楚展示范围。测试跨窗口恢复、同时输入、fork与删除，检查权限变化后旧摘要和在途子Agent是否受到相应处理。\n\n跨设备继续时，应以服务端事件游标和版本为准。客户端重连携带最后已见事件，服务器补发缺失记录；重复输入通过稳定消息身份去重。若离线设备携带旧权限或旧任务限制，应重新获取当前状态，不能让它把过时会话缓存覆盖服务器历史。这种场景需要实际多客户端验证。\n\nSession访问范围由当前身份决定，历史上参与过会话不代表永久拥有全部产物。恢复、分享和导出都应重新执行相应权限检查。\n\n**实践重点**：保存参与者、scope、日志游标与保留策略；resume和fork采用不同身份。\n\n**验证抓手**：验证跨窗口恢复、fork、删除与权限重新核验。\n\n**常见误区**：把会话、业务任务、sandbox和长期记忆合成一行文本。\n\n[Agents SDK：Session接口源码](https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/memory/session.py#L53-L94)；[Claude Code：工作原理](https://code.claude.com/docs/en/how-claude-code-works)。",
      "blueprint": {
        "inputs": [
          "参与者与授权scope",
          "事件历史与游标",
          "关联Task和Run"
        ],
        "steps": [
          "创建或恢复Session身份",
          "排序并追加交互事件",
          "选择当前context",
          "按策略fork或删除"
        ],
        "outputs": [
          "持续会话记录",
          "Context视图",
          "可解释的任务关联"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/memory/session.py#L53-L94",
          "label": "Agents SDK：Session接口源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        },
        {
          "url": "https://code.claude.com/docs/en/how-claude-code-works",
          "label": "Claude Code：工作原理",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": [
        {
          "target": "event-log",
          "type": "requires",
          "reason": "本节点的设计需要先明确事件日志。"
        }
      ]
    },
    {
      "id": "codex",
      "title": "OpenAI Codex",
      "en": "OpenAI Codex",
      "aliases": [
        "Codex CLI",
        "Codex app-server"
      ],
      "kind": "product",
      "parentId": "products-harness",
      "order": 20,
      "summary": "公开Rust CLI源码的代码与文件任务harness，可作为受限worker接入。",
      "question": "它怎样运行Agent，哪些状态和权限仍由应用负责？",
      "body": "观察时点：2026-10-15。公开Rust CLI源码的代码与文件任务harness，可作为受限worker接入。\n\n## 已公开的技术路线与控制边界\n\n模型调用、turn/step、工具执行、权限、子Agent与异步context压缩。公开CLI运行在选定执行环境；app-server/托管服务另有部署控制边界。\n\nCodex公开仓库提供了研究生产级代码Agent的直接入口。固定源码中的Rust核心不止实现模型请求，还处理turn、step、输入队列、工具、权限、子Agent和context rollover。公开CLI、桌面应用和托管服务属于不同交付边界，不能因为共享名称就断言内部实现完全相同。\n\nrun_turn在step边界消费运行中用户输入，并捕获上下文与模型可见工具的统一视图。企业可以借鉴这种“每步冻结、边界更新”的合同：用户修订需要进入当前Task，工具与策略变化要记录何时生效，而非多个线程随意改messages。它有助解释模型为何在某一步选择了某个动作。\n\n异步compaction源码将候选结果绑定历史版本、模型标识、兼容hash和授权代次。后台压缩完成时，历史可能已经变化，不能直接采用旧结果。对企业尤其重要的是保留可回查原事件与证据；模型切换时opaque压缩或reasoning状态可能不兼容，需要从可移植记录重建context。\n\nApache-2.0许可支持在相应条件下复用公开代码，但整体fork的维护范围很大：Rust工具执行、各平台环境、协议、上游快速迭代与provider变化都需要承担。金融、教育和法律的差异能力仍是领域数据、权限、验收与反馈，fork一个coding-agent不会自动得到这些。\n\n优先考虑通过已公开集成路线把Codex当隔离worker或采用托管harness。自己的控制平面保留Task、批准、业务操作和Artifact，Codex负责明确范围的代码与文件工作。若必须改源码，记录upstream、基准SHA、补丁和同步方式，并先证明接口外适配确实不够。\n\n本页源码基线和稳定release分别标注。源码阅读揭示了边界设计，也包含仍在演进的实现，不能据此宣称企业环境已跑通。验证应覆盖用户插话、取消、模型换代、压缩失败、工具unknown和产物读回；完成文字不是交付证明，编译或文件存在也不是全部验收。\n\n例如财报比较可以把提取后的公开数据交给受限Codex worker，让其生成计算脚本和图表；企业服务提供公司、期间和币种合同，并复算关键指标。它不需要直接访问交易账户。法律文书场景则只挂载当前matter的获准材料，发布权仍在外层。恢复实验应对照文件内容、外部工具和业务验收，而不是只检查CLI退出码。保留这种工作边界后，使用公开源码、自运维进程或托管路线都可作同口径比较。\n\n## 数据、记忆与模型替换\n\n固定源码可见输入队列、历史版本、compaction兼容性和授权代次；不等于公开全部桌面或云后端。\n\n有provider能力边界；原生工具和opaque compaction状态不能未经验证跨模型迁移。\n\n## 执行、部署与采用取舍\n\n公开CLI在指定计算环境执行；应用或托管集成路径另有控制合同。模型驱动turn/step循环，含工具、输入steer、子Agent和压缩。CLI、app-server、SDK或托管harness按公开接口选择；不等同同一部署。\n\n固定源码可审查循环与权限边界，适合作为代码文件worker或设计参照。\n\n观察于2026-10-15：代码审阅时间2026-10-15；默认SHA与稳定发行包分别记录；rust-v0.162.1；源码SHA 1ef30bcbe784f1006548adc1542985be32b05109\n\n许可边界：Apache-2.0。采用前按实际使用方式核验组件、云服务与模型条款。\n\n## 证据范围与未知\n\n本页引用固定SHA的loop与compaction代码及Apache-2.0许可。\n\n未公开或仍需目标环境验证的部分：跨模型conformance；企业业务Task模型；公开CLI与云实现是否相同。本页不以产品表面行为推断其隐藏实现。\n\n[OpenAI Codex：固定源码](https://github.com/openai/codex/tree/1ef30bcbe784f1006548adc1542985be32b05109)；[Codex：turn与step循环源码](https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/turn.rs#L454-L518)；[Codex：异步压缩兼容性源码](https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/async_compaction.rs#L23-L117)；[Codex：Apache-2.0许可](https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/LICENSE)；[OpenAI：Agent运行时选择](https://developers.openai.com/api/docs/guides/agents)。",
      "blueprint": {
        "inputs": [
          "业务Task与执行范围",
          "代码或文件输入",
          "版本、工具与验证规则"
        ],
        "steps": [
          "通过受控接口启动Run",
          "在step边界更新输入",
          "执行工具并管理context",
          "导出产物并核查后置条件"
        ],
        "outputs": [
          "代码与文件产物",
          "工具及会话记录",
          "可验证任务结果"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/openai/codex/tree/1ef30bcbe784f1006548adc1542985be32b05109",
          "label": "OpenAI Codex：固定源码",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/turn.rs#L454-L518",
          "label": "Codex：turn与step循环源码",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/async_compaction.rs#L23-L117",
          "label": "Codex：异步压缩兼容性源码",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/LICENSE",
          "label": "Codex：Apache-2.0许可",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://developers.openai.com/api/docs/guides/agents",
          "label": "OpenAI：Agent运行时选择",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": [
        {
          "target": "agent-harness",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent Harness的具体产品路线。"
        },
        {
          "target": "agent-loop",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent执行循环的具体产品路线。"
        },
        {
          "target": "context-compaction",
          "type": "implements",
          "reason": "公开能力或可见源码体现上下文压缩的具体产品路线。"
        },
        {
          "target": "child-agent-contract",
          "type": "implements",
          "reason": "公开能力或可见源码体现子Agent委派合同的具体产品路线。"
        },
        {
          "target": "release-manifest",
          "type": "complements",
          "reason": "用运行版本清单检查采用时的控制边界；不推断未公开内部机制。"
        }
      ],
      "productRoute": {
        "vendor": "OpenAI",
        "category": "开源代码Harness",
        "execution": "公开CLI在指定计算环境执行；应用或托管集成路径另有控制合同。",
        "orchestration": "模型驱动turn/step循环，含工具、输入steer、子Agent和压缩。",
        "context": "固定源码显示step视图、历史版本与异步压缩兼容性检查。",
        "persistence": "固定源码可见输入队列、历史版本、compaction兼容性和授权代次；不等于公开全部桌面或云后端。",
        "modelBoundary": "有provider能力边界；原生工具和opaque compaction状态不能未经验证跨模型迁移。",
        "deployment": "CLI、app-server、SDK或托管harness按公开接口选择；不等同同一部署。",
        "license": "Apache-2.0",
        "availability": "观察于2026-10-15：代码审阅时间2026-10-15；默认SHA与稳定发行包分别记录；rust-v0.162.1；源码SHA 1ef30bcbe784f1006548adc1542985be32b05109",
        "strengths": "固定源码可审查循环与权限边界，适合作为代码文件worker或设计参照。",
        "limits": "待验证或未公开：跨模型conformance；企业业务Task模型；公开CLI与云实现是否相同。公开能力不等同企业负载与领域任务实测。"
      }
    },
    {
      "id": "deadline-propagation",
      "title": "Deadline与剩余预算",
      "en": "Deadline Propagation",
      "aliases": [
        "端到端超时",
        "剩余时间预算"
      ],
      "kind": "concept",
      "parentId": "performance-delivery",
      "order": 20,
      "summary": "把任务的总时限转换为每个下游操作可用时间。",
      "question": "怎样设计Deadline与剩余预算，并验证其对任务质量与可靠性的影响？",
      "body": "把任务的总时限转换为每个下游操作可用时间。\n\nDeadline是整个任务的时间上限，不是每个组件各自默认等待十秒。一次Agent可能经过检索、模型、多个工具和重试；若每层独立使用完整超时，累计时间会远超用户预期。剩余预算应沿调用链传播，并在每次新动作前重新判断。\n\nTask保存绝对截止时间或明确时间窗口，Run和工具执行器计算剩余时长。模型调用、退避、连接重建和验证都消耗这份预算；不能只给主模型设置timeout，却让后台工具无限等待。跨服务传播时使用可信时间源与适当余量，避免依赖客户端时钟。\n\n人工审批等待与活跃计算可分开管理。一个允许跨天等待的流程，不代表sandbox要持续运行三天；恢复后仍检查批准、资源和业务时效。行情或报价任务在排队后可能已失去价值，调度前应重新确认适用窗口，而非只要没执行过就继续。\n\n接近deadline时采用明确策略：停止新搜索、缩小范围、输出已验证部分，或在用户授权下延长。不能为了准时而把未验证内容标成功。已发出的写操作即使超过时限，也要记录最终或unknown状态；timeout不是业务撤销。\n\n重试只使用剩余预算，429的等待建议也需与截止条件协调。若外部系统需要更长完成时间，可转为异步Task并展示状态，而非保持一个即将断开的同步请求。每个子Agent分配的预算还应为父级合并和验证留出时间。\n\n测试慢工具、连续429、队列积压、审批延迟和取消竞态。检查系统能否及时停止新增工作，保留可用产物并解释未完成原因。deadline治理减少不可控等待，也让成本与任务价值的取舍变得可见。\n\n**实践重点**：模型、工具和重试共享剩余deadline；人工等待与计算执行分别处理。\n\n**验证抓手**：模拟慢外部工具，检查停止、降级和剩余成果。\n\n**常见误区**：每个组件独立10秒重试，累计突破用户时限。\n\n[OpenAI：Latency optimization](https://developers.openai.com/api/docs/guides/latency-optimization)；[Temporal：执行状态与外部副作用](https://docs.temporal.io/ai/featured/memory-state-stripe)。",
      "blueprint": {
        "inputs": [
          "Task截止条件",
          "下游操作预计耗时",
          "剩余时间与费用"
        ],
        "steps": [
          "传播绝对deadline",
          "每步重算可用预算",
          "为合并验证留余量",
          "到限停止新动作并保留状态"
        ],
        "outputs": [
          "受控调用时限",
          "可解释降级结果",
          "异步继续或终止决定"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/latency-optimization",
          "label": "OpenAI：Latency optimization",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://docs.temporal.io/ai/featured/memory-state-stripe",
          "label": "Temporal：执行状态与外部副作用",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "business-task",
          "type": "requires",
          "reason": "本节点的设计需要先明确业务Task。"
        }
      ]
    },
    {
      "id": "eval-canary",
      "title": "Canary灰度与线上实验",
      "aliases": [
        "灰度",
        "A/B",
        "实验分流"
      ],
      "kind": "concept",
      "parentId": "evaluation-release",
      "order": 20,
      "summary": "按用户或租户分组发布小流量候选，控制memory污染、动作资格、预算与提前停止风险。",
      "question": "什么实验单位、护栏和停止规则支持逐步扩大流量？",
      "body": "## 小流量不等于随意试验\nCanary将候选版本交给少量真实用户或租户，用受限动作和预算观察实际完成、修订和错误。先有离线合同、完整harness评测和shadow依据，再确定分流比例、观察周期、严重错误停机条件以及可回滚范围。风险高的任务可以先只允许准备草稿，不立即开放外部副作用。\n\n## 选择稳定的实验单位\n按用户、租户或适当业务单元分组，避免同一用户在两版本间反复切换导致memory和行为污染。不同实验组的工具、知识和权限资格应可比；若只给候选简单任务，不能宣称整体提升。对教育按班级或教师聚类，对长期业务任务保留版本归属，不以单条消息随机分流破坏任务连续性。\n\n## 同时观察质量和代价\n监控验收成功、严重错误、人工介入、修订时间、取消、失败恢复、每成功任务费用与P95。预设主要指标与样本预算；反复偷看后在最有利时停止会夸大收益。少量零错误不足以证明稀有风险受控，必要时增加压力测试和更长观察。自动报警要能够追溯到具体trace与产物。\n\n## 扩量和回退都是受控动作\n通过约定门槛后逐步扩量，每一步保留control与可恢复配置。触发回退时先阻止新任务进入候选，明确运行中的任务继续、取消还是迁移。代码回滚不自动撤销新memory、数据库写入或已经送出的消息；这些必须有来源标记、幂等回执与补偿流程。用户感知到的是业务结果，不能只用服务部署成功作为实验完成证明。\n\n将这些检查固定在版本化测试集中，并同时观察通过项与失败项，才能区分真实能力变化与评分尺度变化。\n\n## 避免同一用户跨版本互相影响\n按合适单位稳定分流，而非每条消息随机换模型；教育和长期记忆任务可能需要按学生或团队分配。新增版本写出的记忆应带版本和可撤销来源，实验结束后处理污染与迁移。主要业务指标需要足够观察期，护栏可在严重事件时立即停止，两者是不同停止逻辑。扩量前核权限、依赖容量和回退可用性，并记录为什么继续或终止，避免只因早期几次成功就宣布完成。",
      "blueprint": {
        "inputs": [
          "已过离线及shadow版本",
          "实验单位和稳定分流",
          "护栏预算及停止规则"
        ],
        "steps": [
          "小流量开放明确权限",
          "隔离实验memory",
          "观察严重错误和结果",
          "按预设规则晋升或停止"
        ],
        "outputs": [
          "差异与护栏报告",
          "扩量或回退决定"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent evaluations",
          "kind": "official-doc",
          "note": "官方方法背景；业务阈值与统计合同需独立验证。"
        }
      ],
      "links": [
        {
          "target": "eval-shadow",
          "type": "requires",
          "reason": "先隔离比较，再开放受控真实动作。"
        },
        {
          "target": "eval-statistical-confidence",
          "type": "requires",
          "reason": "分流与停止规则需要统计设计。"
        }
      ],
      "en": "Canary Experiment"
    },
    {
      "id": "grok-bot",
      "title": "Grok Bot",
      "en": "Grok Bot",
      "aliases": [
        "Grok Bots",
        "GrokBot"
      ],
      "kind": "product",
      "parentId": "products-personal",
      "order": 20,
      "summary": "用持久角色、共享云电脑、skills与routines协作的产品。",
      "question": "它怎样运行Agent，哪些状态和权限仍由应用负责？",
      "body": "观察时点：2026-10-15。用持久角色、共享云电脑、skills与routines协作的产品。\n\n## 已公开的技术路线与控制边界\n\n具名Bot角色＋跨session记忆＋共享电脑＋技能流程与触发。同账号Bots共享文件、浏览器session与登录；角色不是VM或租户隔离边界。\n\nGrok Bot公开产品以具名、持久角色组织工作，并提供跨session记忆、云端电脑、协作、skills和routines。对企业最重要的不是角色数量，而是共享边界：官方说明同账号Bots共享文件、浏览器session和登录，各自角色与对话分开。因此Bot名称并不是数据或计算隔离单位。\n\n共享环境可以减少重复登录和文件搬运，但不同职责也可能接触同一敏感状态。金融、法律和教育组织若采用类似设计，应在界面明确显示哪些文件、账号和凭证被共享，按真实资源scope控制动作。不能因为开了三个Bot就承诺三个独立VM，更不能把角色当租户边界。\n\n复制与删除也有独立语义。官方Bots文档说明模板或复制主要迁移配置、skills和routines，不复制对话、learned memory与附件，接收者不会获得原账号电脑与登录。删除某个Bot也不一定清理共享电脑文件。企业应将能力复用和私人状态迁移设计为不同操作，并解释各自后果。\n\nSkill是可复用方法，routine是按时间或支持事件触发；二者不等于模型权重训练。Teach-by-demonstration仍是渐进开放，生成的skill是候选草稿，应补充异常、批准范围并测试。一次演示成功不能证明对任意输入形成泛化能力，尤其不能自动升级成全组织强制规则。\n\n角色长期运行还需要owner、工作范围、deadline、成本与停止条件。不同Bot交换结论时仍要保留证据和结构化产物，不能把对方返回视为高优先级指令。共享环境下取消一个任务，也要明确是否影响其他仍合法运行的工作。\n\n公开产品文档证明上述配置和共享合同，不证明完整runtime开源或已提供第三方Bot管理API；网站出现模型API导航也不能自动推导Bot可嵌入。套餐、平台、地区和实际账号资格未在本页逐项实测。适合把它作为多角色持续产品参照，而非企业框架可复用代码候选。\n\n如果企业采用共享电脑上的多个角色，建议把共享文件夹、浏览器登录和敏感连接作为一等资源展示；每个Bot只获准在其任务scope内使用。创建研究角色与发送角色并不能形成安全隔离，真实动作还要网关和审批。复制一个skill时，应同时携带适用范围与测试条件，不复制原用户私人状态。对routine安排明确owner、费用上限、停止和错误通知策略。该设计借鉴公开能力，但关于内部调度、技能评分和长期记忆数据库的机制仍需证据，不以产品表面行为推断。\n\n## 数据、记忆与模型替换\n\n配置/skill/routine复制与私人对话、learned memory、附件分开；删除Bot不必然清共享文件。\n\n公开配置能力不等于任意模型替换或第三方Bot管理API。\n\n## 执行、部署与采用取舍\n\n同账号Bots共享云电脑文件、浏览器session与登录。多个具名角色协作；skills复用方法，routines触发工作。官方Grok Bot产品，平台、套餐与地区条件分别核查。\n\n角色配置、技能复用和触发合同具体；共享环境必须可见。\n\n观察于2026-10-15：按平台、套餐、地区与渐进开放功能核验。\n\n许可边界：商业产品条款。采用前按实际使用方式核验组件、云服务与模型条款。\n\n## 证据范围与未知\n\nxAI官方overview、Bots、Skills文档有明确共享与复制边界。\n\n未公开或仍需目标环境验证的部分：完整runtime源码；对外Bot管理API范围；套餐地区采购矩阵。本页不以产品表面行为推断其隐藏实现。\n\n[Grok Bot：Overview](https://docs.x.ai/grok-bot/overview)；[Grok Bot：角色与共享状态](https://docs.x.ai/grok-bot/bots)；[Grok Bot：Skills and routines](https://docs.x.ai/grok-bot/skills-routines-and-automations)。",
      "blueprint": {
        "inputs": [
          "持久Bot角色与owner",
          "共享电脑和连接",
          "Skills及routine配置"
        ],
        "steps": [
          "明确共享资源边界",
          "配置角色与任务",
          "审查并测试技能候选",
          "跟踪触发、取消和交付"
        ],
        "outputs": [
          "角色化任务结果",
          "可复用方法配置",
          "共享及私人状态说明"
        ]
      },
      "citations": [
        {
          "url": "https://docs.x.ai/grok-bot/overview",
          "label": "Grok Bot：Overview",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://docs.x.ai/grok-bot/bots",
          "label": "Grok Bot：角色与共享状态",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://docs.x.ai/grok-bot/skills-routines-and-automations",
          "label": "Grok Bot：Skills and routines",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": [
        {
          "target": "agent-definition-version",
          "type": "complements",
          "reason": "用Agent定义与版本检查采用时的控制边界；不推断未公开内部机制。"
        },
        {
          "target": "agent-session",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent Session的具体产品路线。"
        },
        {
          "target": "sandbox-lifecycle",
          "type": "implements",
          "reason": "公开能力或可见源码体现沙箱生命周期的具体产品路线。"
        },
        {
          "target": "child-agent-contract",
          "type": "implements",
          "reason": "公开能力或可见源码体现子Agent委派合同的具体产品路线。"
        },
        {
          "target": "human-approval",
          "type": "implements",
          "reason": "公开能力或可见源码体现人工审批合同的具体产品路线。"
        }
      ],
      "productRoute": {
        "vendor": "xAI",
        "category": "持久角色与云电脑产品",
        "execution": "同账号Bots共享云电脑文件、浏览器session与登录。",
        "orchestration": "多个具名角色协作；skills复用方法，routines触发工作。",
        "context": "角色和对话分开，支持跨session记忆；同账号电脑与登录共享。",
        "persistence": "配置/skill/routine复制与私人对话、learned memory、附件分开；删除Bot不必然清共享文件。",
        "modelBoundary": "公开配置能力不等于任意模型替换或第三方Bot管理API。",
        "deployment": "官方Grok Bot产品，平台、套餐与地区条件分别核查。",
        "license": "商业产品条款",
        "availability": "观察于2026-10-15：按平台、套餐、地区与渐进开放功能核验。",
        "strengths": "角色配置、技能复用和触发合同具体；共享环境必须可见。",
        "limits": "待验证或未公开：完整runtime源码；对外Bot管理API范围；套餐地区采购矩阵。公开能力不等同企业负载与领域任务实测。"
      }
    },
    {
      "id": "knowledge-ingestion",
      "title": "接入与解析",
      "aliases": [
        "ingestion",
        "document processing"
      ],
      "kind": "branch",
      "parentId": "knowledge",
      "order": 20,
      "summary": "接入完整对象，恢复可检索的文档结构与视觉语义。",
      "question": "怎样把异构资料变成结构正确的知识对象？",
      "body": "接入与解析负责把异构资料变成可追溯、可重复加工的结构化对象。首先确认源系统怎样描述对象、分页、变化与删除，再决定文件内容怎样进入知识服务。\n\n这一组包含三个连续但可独立验证的边界：连接器证明是否完整获取源对象；解析器恢复文字、阅读顺序和定位；表格与多模态处理保留关系、单位与视觉证据。任何一层的成功回执都不能自动证明下一层正确。保留原件和中间表示，才能在解析或模型变化时重建并定位错误。",
      "blueprint": {
        "inputs": [
          "源对象与原件"
        ],
        "steps": [
          "验证连接器合同",
          "恢复文字与版面",
          "保留表格和图像语义"
        ],
        "outputs": [
          "结构化文档与原件定位"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/docling-project/docling",
          "label": "Docling：解析能力",
          "kind": "code"
        }
      ],
      "links": []
    },
    {
      "id": "memory-types",
      "title": "记忆的内容类型",
      "aliases": [],
      "kind": "branch",
      "parentId": "memory",
      "order": 20,
      "summary": "事实与偏好描述当前已知信息，episode保存某次经历，Task记忆维持目标理解，程序记忆表达有条件的做法。",
      "question": "记忆究竟保存什么？",
      "body": "事实与偏好描述当前已知信息，episode保存某次经历，Task记忆维持目标理解，程序记忆表达有条件的做法。这些类型可以互相提供证据，但不能自动互相升级。\n\n本组以内容语义确定写入与使用方式。Task摘要不替代checkpoint，单次经历不等于通用技能，个人偏好不构成企业规则。明确类型之后，表示、权限和验证才能各自对应具体要求。",
      "blueprint": {
        "inputs": [
          "记忆合同和任务需要"
        ],
        "steps": [
          "按子节点选择机制",
          "验证跨Session效果与边界"
        ],
        "outputs": [
          "可维护的记忆设计"
        ]
      },
      "citations": [
        {
          "url": "https://docs.langchain.com/oss/python/concepts/memory",
          "label": "官方机制与实现参考",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "model-capability-registry",
      "title": "模型能力注册",
      "en": "Model Capability Registry",
      "aliases": [
        "能力矩阵",
        "Feature Registry"
      ],
      "kind": "concept",
      "parentId": "models-contracts",
      "order": 20,
      "summary": "记录每模型及适配器可实际使用的能力和限制。",
      "question": "怎样设计模型能力注册，并验证其对任务质量与可靠性的影响？",
      "body": "记录每模型及适配器可实际使用的能力和限制。\n\n能力注册表记录的是某个模型、provider与adapter组合实际能使用什么，而不是模型名称旁的营销标签。相同模型在不同云平台、API版本或套餐下，原生搜索、缓存、输出schema和上下文限制都可能不同。Agent在调用前需要能判断哪些能力可用。\n\n建议条目包含消息角色、并行工具、严格schema支持范围、多模态、引用、原生工具、reasoning参数、最大输入输出、compaction和缓存合同。每一项都带观察日期、文档依据和契约测试结果，区分公开支持、已在目标环境验证、未知与不支持。没有测过的能力不应填成默认通过。\n\n运行时根据表选择合法路径。例如模型不支持某种严格输出模式，可由应用解析并验证普通结构化输出，但这是不同保证；不支持native search时可接独立检索工具；不支持跨模型压缩状态时，从事件重新组装context。降级可能增加调用和延迟，必须进入预算和质量评测。\n\n能力表还帮助定义路由资格。高风险任务只能进入获准处理相关数据、具备所需工具和格式能力的模型集合，再比较质量和成本。不能因为备用模型价格低或服务健康，就忽略数据合同和关键能力缺失。恢复旧Run时也要确认当前端点仍满足原合同。\n\nPydantic AI将core与Harness capabilities分层，OpenAI SDK提供provider扩展，都说明能力可以组合，但不等于跨模型等价。企业应固定adapter版本，并测试工具schema与provider变化。\n\n可为每次发布生成一张能力矩阵，配简短探针持续检查。探针发现变化应触发调查或降级，不能自动证明业务质量提升。注册表是执行选择的依据，不是对准确率的排行榜；支持tools仅证明协议入口存在，正确使用工具还要靠任务评测。\n\n表中还应记录能力验证所用环境与日期，部署后端变化时重新核验。\n\n**实践重点**：登记并行工具、schema、多模态、context、缓存、compaction和停止原因。\n\n**验证抓手**：对每项capability保存契约测试和明确降级路径。\n\n**常见误区**：统一API抹平差异，生产才发现功能不支持。\n\n[OpenAI Agents SDK：模型与provider](https://developers.openai.com/api/docs/guides/agents/models)；[Pydantic AI：Harness能力边界](https://pydantic.dev/docs/ai/harness/)。",
      "blueprint": {
        "inputs": [
          "模型与provider配置",
          "官方能力声明",
          "Adapter契约测试"
        ],
        "steps": [
          "登记能力和限制",
          "区分支持与已验证",
          "定义显式降级",
          "发布并持续探测"
        ],
        "outputs": [
          "能力矩阵",
          "合法路由集合",
          "兼容性变化记录"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/agents/models",
          "label": "OpenAI Agents SDK：模型与provider",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://pydantic.dev/docs/ai/harness/",
          "label": "Pydantic AI：Harness能力边界",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "model-adapter",
          "type": "requires",
          "reason": "本节点的设计需要先明确模型适配层。"
        }
      ]
    },
    {
      "id": "model-failover",
      "title": "模型故障切换",
      "en": "Model Failover",
      "aliases": [
        "故障切换",
        "Fallback"
      ],
      "kind": "concept",
      "parentId": "models-release",
      "order": 20,
      "summary": "在模型服务失败时使用获准的替代路径。",
      "question": "怎样设计模型故障切换，并验证其对任务质量与可靠性的影响？",
      "body": "在模型服务失败时使用获准的替代路径。\n\n故障切换应保持任务合同，而不只是恢复一个HTTP响应。供应商不可用时，备用模型必须有权处理相同数据，具备所需工具和输出能力，并能接受可移植上下文。若不满足，应排队、返回部分结果或明确降级，不能静默发送到未批准端点。\n\n不同模型不共享隐式推理和原生compaction状态。Codex公开异步压缩代码将结果绑定模型、历史版本和授权代次，说明状态兼容性本身需要协议。跨供应商切换通常要从任务状态、已确认工具结果、证据和用户限制重建context，而不是复制一个opaque token继续。\n\n切换前检查外部动作状态。原请求断流时，模型或工具可能已经产生部分结果；备用模型应知道哪些操作已提交、哪些未知。重复完整请求可能重新执行副作用。稳定业务ID和read-back仍然有效，换模型不能成为创建新动作身份的理由。\n\n路由策略还需处理错误分类。短暂429可能等待更经济，持续故障才切换；权限或数据驻留不合格不能靠fallback解决；备用服务自身配额也有限。熔断、恢复探测和切回应有节制，避免故障期间反复摇摆并破坏缓存。\n\n验证不应只关掉主模型看备用是否回答。应测试同类数据资格、schema差异、长上下文、并行工具、拒绝与取消，并核对费用和外部效果。关键领域可选择只允许新Task使用备用模型，在途高风险Task暂停等待确认。\n\n向用户说明降级影响，例如来源覆盖减少、响应延后或某项计算尚未完成。故障恢复的目标是维持可解释可靠性，不能为了隐藏服务异常而输出未经同等验证的结论。\n\n切回主模型也属于变更，不能自动复用备用模型的opaque上下文。应记录切换点，并核对待执行动作。\n\n**实践重点**：备选具备同类数据处理资格、schema和verifier；否则排队或降级。\n\n**验证抓手**：模拟供应商故障，验证数据合同和上下文重建。\n\n**常见误区**：静默送往未批准供应商，或迁移opaque推理状态。\n\n[OpenAI：Agent运行时选择](https://developers.openai.com/api/docs/guides/agents)；[Codex：异步压缩兼容性源码](https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/async_compaction.rs#L23-L117)。",
      "blueprint": {
        "inputs": [
          "供应商故障信息",
          "备用模型资格",
          "可移植任务状态"
        ],
        "steps": [
          "分类故障与等待价值",
          "核验数据及功能资格",
          "重建context并核对效果",
          "切换或明确降级"
        ],
        "outputs": [
          "获准备用执行",
          "状态兼容记录",
          "降级与排队说明"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/agents",
          "label": "OpenAI：Agent运行时选择",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/async_compaction.rs#L23-L117",
          "label": "Codex：异步压缩兼容性源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "model-adapter",
          "type": "requires",
          "reason": "本节点的设计需要先明确模型适配层。"
        },
        {
          "target": "context-compaction",
          "type": "requires",
          "reason": "本节点的设计需要先明确上下文压缩。"
        }
      ]
    },
    {
      "id": "models-contracts",
      "title": "模型接口与能力",
      "en": "Model Contracts",
      "aliases": [],
      "kind": "branch",
      "parentId": "models",
      "order": 20,
      "summary": "统一基础事件，同时显式保留功能与语义差异。",
      "question": "怎样把模型接口与能力落实为可比较和可验证的工程选择？",
      "body": "Adapter处理协议转换，能力表决定合法路径，call ID维护工具配对，schema约束输出形状。它们是互补机制。协议测试要进入真实harness验证，格式正确不能替代语义正确；缺失数据应保留未知，不由统一层虚构默认保证。\n\n[Agents SDK：Model接口和call ID约束](https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/models/interface.py#L37-L80)；[OpenAI Agents SDK：模型与provider](https://developers.openai.com/api/docs/guides/agents/models)。",
      "blueprint": {
        "inputs": [
          "Provider协议",
          "工具与输出schema"
        ],
        "steps": [
          "映射消息和流",
          "登记能力边界",
          "配对调用结果",
          "验证结构和语义"
        ],
        "outputs": [
          "Conformance结果",
          "合法能力路径"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/models/interface.py#L37-L80",
          "label": "Agents SDK：Model接口和call ID约束",
          "kind": "code",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://developers.openai.com/api/docs/guides/agents/models",
          "label": "OpenAI Agents SDK：模型与provider",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": []
    },
    {
      "id": "openai-agents-api",
      "title": "OpenAI Agents API",
      "en": "OpenAI Agents API",
      "aliases": [
        "Agents API",
        "Managed Codex Harness"
      ],
      "kind": "product",
      "parentId": "products-platforms",
      "order": 20,
      "summary": "由OpenAI运行Codex harness并保存进度的托管Agent API。",
      "question": "它怎样运行Agent，哪些状态和权限仍由应用负责？",
      "body": "观察时点：2026-10-15。由OpenAI运行Codex harness并保存进度的托管Agent API。\n\n## 已公开的技术路线与控制边界\n\n托管循环、context compaction、多Agent与工具集成，可配置执行环境。OpenAI管理runtime；应用管理业务记录、工具handler、权限、验收与用户界面。\n\n当前OpenAI官方文档已将Agents API、应用内Agents SDK与直接Responses API分开。Agents API由OpenAI运行Codex harness并管理执行进度；SDK让应用掌握循环部署与存储；Responses则提供更底层模型接入。企业自建不再必然意味着从零维护全部循环和sandbox。\n\n托管路线可以减少context compaction、多Agent协调、工具编程和环境基础设施的工程量，但它不会定义企业业务对象。Task、客户matter、课程身份、证据版本和最终批准仍应有自有合同。一个托管session可能承载交互或任务连续性，不应直接替代所有业务记录。\n\n接入时为每个Task保存对应session、turn、item、sandbox和artifact引用，区分它们的生命周期。模型调用状态、工具回调、产物生成与业务完成是不同事件。应用函数handler需执行当前授权、幂等和回执确认，托管服务返回completed只能触发外层verification。\n\n环境可以是厂商托管sandbox、自有环境或不需要sandbox的工具任务，具体能力以当前API和账号为准。公开文档说明架构，不证明特定租户已经具备所有区域、配额和功能。模型与托管harness的可替换范围也需按服务能力核验，不能从“可配置Agent”推断能直接接任意微调模型。\n\n适合先做单厂商长任务验证，尤其代码或文件执行是主要需求时。为了保留退出路径，应导出通用产物、必要事件和证据，不只保存opaque provider state。若同时评估Pydantic或LangGraph路线，使用同一任务、工具后端与验收标准，比较人力维护、成功率、尾延迟和总成本。\n\n采购测试重点是session恢复与删除、回调重投、工具身份、审批、产物导出、区域和计费。服务保存了进度，不等于外部副作用exactly-once；应用仍要稳定操作ID和read-back。对公开资料未明确的内部调度、grader和存储机制，本页不作推断。\n\n例如一个异步财报任务可以由自有API创建Task，随后提交托管session；应用handler提供受权限约束的资料读取和确定性计算。事件流只更新进度，最终产物回到企业对象存储并由verifier检查。工具回调重投时使用同一业务操作ID，避免任务恢复创建重复记录。测试中还要检查Session关闭、sandbox销毁与Task取消是否分别符合产品策略。这样的合同使托管能力成为可替换执行平面，而不是整个业务数据库。对暂时不可用的模型或区域，应明确排队与降级，不让备用路径突破原数据合同。\n\n## 数据、记忆与模型替换\n\n服务session配置、turns与items不同于SDK Session、Responses conversation和sandbox。\n\n托管能力与厂商模型耦合；不能推断任意第三方模型可替换harness。\n\n## 执行、部署与采用取舍\n\nOpenAI管理Agent基础设施；工具handler和业务系统由应用接入。托管循环、自动context压缩、多Agent与工具编程能力按API提供。通过Agents API；托管、自有或无sandbox环境按能力选择。\n\n降低完整runtime运维投入，保留自有应用控制与领域能力。\n\n观察于2026-10-15：以实际账号、区域和API合同验证。\n\n许可边界：商业服务条款。采用前按实际使用方式核验组件、云服务与模型条款。\n\n## 证据范围与未知\n\n当前官方runtime对照明确区分Agents API、Agents SDK与Responses API。\n\n未公开或仍需目标环境验证的部分：账号和区域可用性；资源导出删除合同；目标业务SLA和模型替换范围。本页不以产品表面行为推断其隐藏实现。\n\n[OpenAI：Agent运行时选择](https://developers.openai.com/api/docs/guides/agents)；[OpenAI：托管Agents架构](https://developers.openai.com/api/docs/guides/agents-api/architecture)。",
      "blueprint": {
        "inputs": [
          "Task合同及Agent配置",
          "工具函数与MCP连接",
          "应用业务状态和验收"
        ],
        "steps": [
          "创建托管资源",
          "运行并消费事件",
          "执行受控工具handler",
          "导出和验证产物"
        ],
        "outputs": [
          "托管session执行",
          "应用侧业务回执",
          "经验证的任务产物"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/agents",
          "label": "OpenAI：Agent运行时选择",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://developers.openai.com/api/docs/guides/agents-api/architecture",
          "label": "OpenAI：托管Agents架构",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": [
        {
          "target": "agent-harness",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent Harness的具体产品路线。"
        },
        {
          "target": "agent-session",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent Session的具体产品路线。"
        },
        {
          "target": "sandbox-lifecycle",
          "type": "implements",
          "reason": "公开能力或可见源码体现沙箱生命周期的具体产品路线。"
        },
        {
          "target": "tool-authorization",
          "type": "implements",
          "reason": "公开能力或可见源码体现工具授权网关的具体产品路线。"
        },
        {
          "target": "checkpoint-recovery",
          "type": "complements",
          "reason": "用Checkpoint与恢复检查采用时的控制边界；不推断未公开内部机制。"
        }
      ],
      "productRoute": {
        "vendor": "OpenAI",
        "category": "托管Codex Harness API",
        "execution": "OpenAI管理Agent基础设施；工具handler和业务系统由应用接入。",
        "orchestration": "托管循环、自动context压缩、多Agent与工具编程能力按API提供。",
        "context": "托管Codex harness管理context，自动压缩等能力按实际API合同提供。",
        "persistence": "服务session配置、turns与items不同于SDK Session、Responses conversation和sandbox。",
        "modelBoundary": "托管能力与厂商模型耦合；不能推断任意第三方模型可替换harness。",
        "deployment": "通过Agents API；托管、自有或无sandbox环境按能力选择。",
        "license": "商业服务条款",
        "availability": "观察于2026-10-15：以实际账号、区域和API合同验证。",
        "strengths": "降低完整runtime运维投入，保留自有应用控制与领域能力。",
        "limits": "待验证或未公开：账号和区域可用性；资源导出删除合同；目标业务SLA和模型替换范围。公开能力不等同企业负载与领域任务实测。"
      }
    },
    {
      "id": "parallel-result-merge",
      "title": "并行结果合并",
      "en": "Parallel Result Merge",
      "aliases": [
        "Fan-out/Fan-in",
        "结果汇总"
      ],
      "kind": "concept",
      "parentId": "runtime-delegation",
      "order": 20,
      "summary": "将独立分支产物去重、核验和整合到业务结果。",
      "question": "怎样合并并行结果，并处理同源与冲突？",
      "body": "将独立分支产物去重、核验和整合到业务结果。\n\n并行的价值取决于任务能否分解成独立工作，以及合并是否可靠。分别调查支持与反证、不同公司或不同来源集合，通常比让多个Agent同时编辑同一段报告更容易控制。总耗时接近最慢分支加合并时间，但总模型与工具费用仍会累加。\n\n不同角色名不等于独立证据。同一模型、同一搜索引擎和相同网页可能产生高度相关错误；三个Agent重复引用同一新闻，不是三个独立来源。合并器要去重来源和claim，保留相互冲突的结论，并回到原始材料核验关键事实，不能按多数票决定真相。\n\n每个分支应采用可比的产物schema，包含结论、证据定位、时间范围、假设、未决问题和验证结果。合并规则明确哪些字段可求和、哪些需要重新计算、哪些必须人工判断。例如公司的不同财年数据不能直接按季度名称拼表；法律不同法域意见也不能平均成统一建议。\n\n共享写入要另有协调。代码、合同或业务记录应分配owner、隔离工作区或使用乐观版本，合并前检查目标版本。多Agent并不提供分布式事务。测试比较同任务的单Agent与并行版本，报告完成率、关键路径、重复来源、冲突处理与有效结果成本。若并行只增加观点数量而没有提高验证后产出，就不应作为默认架构。\n\n合并失败也要可恢复。一个分支超时不应使所有正确成果丢失；可以保留已验证产物，标出覆盖缺口，再决定重跑该分支或人工补充。若任务要求全部公司可比，缺一分支则不能发布完整比较结论；若允许局部结果，应在产物中明确边界，避免读者误解覆盖范围。\n\n**实践重点**：定义每分支责任与合并schema；去重同源证据并保留冲突。\n\n**验证抓手**：比较串行与并行质量、关键路径时间和总成本。\n\n**常见误区**：角色名不同就认为独立，或并行写共享记录产生覆盖。\n\n[LangGraph：Runner提交源码](https://github.com/langchain-ai/langgraph/blob/889a5ff16f8325113093d517dffd5471a943c760/libs/langgraph/langgraph/pregel/_runner.py#L575-L615)；[Anthropic：Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)。",
      "blueprint": {
        "inputs": [
          "分支产物schema",
          "各自证据与假设",
          "合并及冲突规则"
        ],
        "steps": [
          "并行执行独立任务",
          "去重同源证据",
          "核查冲突与可比性",
          "验证合并产物"
        ],
        "outputs": [
          "统一证据产物",
          "冲突与缺口清单",
          "关键路径和总成本"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/langchain-ai/langgraph/blob/889a5ff16f8325113093d517dffd5471a943c760/libs/langgraph/langgraph/pregel/_runner.py#L575-L615",
          "label": "LangGraph：Runner提交源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        },
        {
          "url": "https://www.anthropic.com/engineering/building-effective-agents",
          "label": "Anthropic：Building effective agents",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": [
        {
          "target": "child-agent-contract",
          "type": "requires",
          "reason": "本节点的设计需要先明确子Agent委派合同。"
        },
        {
          "target": "completion-contract",
          "type": "requires",
          "reason": "本节点的设计需要先明确任务完成合同。"
        }
      ]
    },
    {
      "id": "performance-delivery",
      "title": "延迟、容量与结果成本",
      "en": "Delivery Performance",
      "aliases": [],
      "kind": "branch",
      "parentId": "performance",
      "order": 20,
      "summary": "让工作在可控资源内及时完成，并计算真实结果成本。",
      "question": "怎样把延迟、容量与结果成本落实为可比较和可验证的工程选择？",
      "body": "关键路径解释时间，deadline约束等待与重试，背压协调需求和配额，有效结果成本连接技术费用与人工价值。分别报告交互、异步研究和执行任务，保留冷缓存、失败和热点租户场景，避免平均值掩盖尾部体验。\n\n[OpenAI：Latency optimization](https://developers.openai.com/api/docs/guides/latency-optimization)；[Temporal：执行状态与外部副作用](https://docs.temporal.io/ai/featured/memory-state-stripe)。",
      "blueprint": {
        "inputs": [
          "任务分布",
          "资源配额及账单"
        ],
        "steps": [
          "分层测量时间",
          "传播剩余预算",
          "公平排队与背压",
          "比较通过验收的成本"
        ],
        "outputs": [
          "SLO和容量计划",
          "质量成本取舍"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/latency-optimization",
          "label": "OpenAI：Latency optimization",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://docs.temporal.io/ai/featured/memory-state-stripe",
          "label": "Temporal：执行状态与外部副作用",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": []
    },
    {
      "id": "products-frameworks",
      "title": "应用内框架与SDK",
      "en": "Application Frameworks and SDKs",
      "aliases": [],
      "kind": "branch",
      "parentId": "products",
      "order": 20,
      "summary": "比较开发抽象、状态恢复和Provider边界。",
      "question": "怎样按技术路线和控制边界比较应用内框架与SDK？",
      "body": "框架和SDK让应用掌握不同程度的循环、图状态、模型与持久化。选择一个主runtime并明确等待、重试和恢复权威，比同时堆叠多套库更重要。模型兼容先做协议测试，再做真实任务；类型与图都不能代替业务证据。\n\n[Agents SDK：Model接口和call ID约束](https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/models/interface.py#L37-L80)；[LangGraph：Checkpointer与Store](https://docs.langchain.com/oss/python/langgraph/persistence)；[Pydantic AI：Harness能力边界](https://pydantic.dev/docs/ai/harness/)。",
      "blueprint": {
        "inputs": [
          "团队栈与任务合同",
          "模型工具和状态需求"
        ],
        "steps": [
          "选择主运行权威",
          "比较扩展与存储",
          "做同任务验证",
          "评估维护和退出"
        ],
        "outputs": [
          "可采用候选",
          "框架集成边界"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/models/interface.py#L37-L80",
          "label": "Agents SDK：Model接口和call ID约束",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://docs.langchain.com/oss/python/langgraph/persistence",
          "label": "LangGraph：Checkpointer与Store",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://pydantic.dev/docs/ai/harness/",
          "label": "Pydantic AI：Harness能力边界",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": []
    },
    {
      "id": "prompt-registry",
      "title": "Prompt版本与发布",
      "en": "Prompt Registry",
      "aliases": [
        "提示词版本管理",
        "Prompt Ops"
      ],
      "kind": "concept",
      "parentId": "models-context",
      "order": 20,
      "summary": "将应用指令当可评测、可回滚且有适用范围的发布资产。",
      "question": "怎样设计Prompt版本与发布，并验证其对任务质量与可靠性的影响？",
      "body": "将应用指令当可评测、可回滚且有适用范围的发布资产。\n\nPrompt registry把应用指令变成可审查和可回滚的发布资产。它不只是存一份字符串，而是保存模块身份、语义版本、正文hash、变量schema、适用模型、工具依赖、owner、变更原因和评测证据。这样才能回答某次行为变化究竟来自哪条规则。\n\n可将稳定应用合同、领域规则、任务模板和局部方法拆成小模块。每个模块有明确作用域和组合顺序；只允许受信角色修改应用规则。上传文档、工具结果或自动提炼的经验不得直接覆盖生产prompt。候选改进先进入实验，经过对照和批准后再发布。\n\n实际执行还要记录渲染后的内容引用。只保存模板名不足以复现，因为变量、默认值、模块顺序和工具定义可能已改变。敏感变量可以保存加密快照或受限引用；trace记录对应hash，避免复制私人材料。运行清单应能从产物追到当时使用的模块与参数。\n\n历史补丁尤其需要管理。旧模型可能需要强制分步、新模型可能在同一规则下反而效率下降；某次失败的临时提醒也可能与其他规则冲突。给workaround写适用版本、根因与删除条件，升级时对原规则、删补丁版本和新规则做消融，而非无限叠加。\n\nPrompt更新不是纯文案修改。改变完成条件、来源范围、工具选择或审批描述，都可能改变业务行为。实验先固定模型、检索和工具，单独改指令，再测组合效应；既跑旧失败例，也用未见样例检查泛化。通过后发布灰度并保留完整回滚目标，而不是仅把线上文本替换掉。\n\nClaude Code文档明确项目指令属于context而非强制配置，这提醒registry不能取代权限系统。即使规则版本被回滚，已经发送的消息和写入的记录也不会自动撤销；发布流程需检查在途Run与副作用。\n\n**实践重点**：保存模块ID、正文hash、变量schema、模型/工具适用版本、owner、评测与回滚目标。\n\n**验证抓手**：重建实际渲染输入，对旧workaround做消融与未见任务回归。\n\n**常见误区**：只记录模板名，或把历史补丁永久叠加到巨型system prompt。\n\n[OpenAI：Prompt engineering](https://developers.openai.com/api/docs/guides/prompt-engineering)；[Claude Code：指令与记忆](https://code.claude.com/docs/en/memory)。",
      "blueprint": {
        "inputs": [
          "Prompt模块与变量schema",
          "模型和工具版本",
          "实验及批准报告"
        ],
        "steps": [
          "登记正文与依赖hash",
          "渲染并记录输入引用",
          "对照和消融验证",
          "灰度发布并保留回滚"
        ],
        "outputs": [
          "Prompt版本目录",
          "可定位运行输入",
          "发布与回滚记录"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/prompt-engineering",
          "label": "OpenAI：Prompt engineering",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://code.claude.com/docs/en/memory",
          "label": "Claude Code：指令与记忆",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "instruction-roles",
          "type": "requires",
          "reason": "本节点的设计需要先明确指令角色与信任边界。"
        },
        {
          "target": "release-manifest",
          "type": "requires",
          "reason": "本节点的设计需要先明确运行版本清单。"
        }
      ]
    },
    {
      "id": "pydantic-ai",
      "title": "Pydantic AI",
      "en": "Pydantic AI",
      "aliases": [
        "PydanticAI",
        "Pydantic AI Harness"
      ],
      "kind": "product",
      "parentId": "products-frameworks",
      "order": 20,
      "summary": "以强类型接口构建Agent，并以独立Harness扩展长任务能力。",
      "question": "它怎样运行Agent，哪些状态和权限仍由应用负责？",
      "body": "观察时点：2026-10-15。以强类型接口构建Agent，并以独立Harness扩展长任务能力。\n\n## 已公开的技术路线与控制边界\n\ntyped tools/outputs/dependencies＋capabilities；Harness提供记忆、委派与context能力，可接durability引擎。应用掌握类型、依赖、工具和存储；core与Harness是包边界，并非成熟度档位。\n\nPydantic AI当前已经形成typed核心与独立Harness，不宜沿用“只是一层类型封装”的早期印象。核心把模型、工具、依赖和输出纳入Python类型体系，Harness以capabilities扩展文件、记忆、委派和长任务。官方说明这是包职责边界，不是成熟度档位。\n\n类型化接口适合财报指标、引证对象和教学rubric等领域结构。它可以让应用明确每个字段的形状，并提高依赖注入与工具开发的可维护性；但不能证明字段真实或法律适用。模型生成的数值、引用和评价仍要外部证据与领域verifier，schema通过率不能替代业务成功率。\n\n固定memory源码很值得借鉴：默认guidance将记忆定义为背景而非instructions，volatile事实需重新验证；主笔记有限注入，主题内容按需读取；namespace由配置或运行时resolver提供，不暴露给模型自由选择。它还限制token、行数、文件大小和搜索范围，默认内存store仅在进程生命周期有效。\n\nDurability通过已有集成扩展，例如Temporal、DBOS或Prefect。采用前先明确主循环和恢复权威，避免在外层持久引擎与内层能力之间重复执行。能力组合虽方便，不同provider对native工具、schema和compaction支持并不等价，每个组合仍需conformance与真实任务验证。\n\n对Python团队，可先与LangGraph做同一用例对照：若问题主要是类型化工具和局部探索，typed loop可能更轻；若流程已有复杂审批与明确阶段，图的控制方式可能更直观。不要为了“全面支持”同时堆多套主runtime，也不必从头实现框架已经提供的存储接口。\n\nMIT许可适合以依赖方式集成，优先在应用层保持业务Task、权限、证据和评测资产独立。试验覆盖memory scope、context压缩后约束、provider切换、工具副作用和重启。公开文档与固定源码证明这些设计入口，不能代替企业数据、三域质量或多实例恢复实测。\n\n领域对象可以从最小集合开始，例如指标值、单位、期间、source_version和计算过程；引用对象保存原文定位与支持关系；教学观察保存题目、提示程度和不确定性。类型让这些差别显式，但每个字段仍需证据。针对memory，应让运行时resolver依据当前用户和项目确定namespace，禁止模型选择别人的scope。换模型后重测数字转换、日期、枚举和缺失值；若严格schema不可用，明确降级保证。这样的切片能评估类型体系带来的实际维护收益，而非只比较代码行数。\n\n## 数据、记忆与模型替换\n\n源码把memory作为背景而非指令；namespace由运行时提供并限制注入规模；默认内存store非持久后端。\n\n支持多provider；模型字符串可换不代表每个capability跨厂商行为相同。\n\n## 执行、部署与采用取舍\n\n在应用选择的Python运行环境执行；持久后端按需接入。Typed loop配capabilities；可接现有durable execution引擎。云端API服务、worker或所选持久执行平台。\n\n强类型、依赖注入与多provider边界适合维护领域工具及开放模型路线。\n\n观察于2026-10-15：具体capability和接口成熟度按文档逐项核实；v2.56.0；SHA f2d82f53873eb94614c23108b2045748b9c72252\n\n许可边界：MIT。采用前按实际使用方式核验组件、云服务与模型条款。\n\n## 证据范围与未知\n\n已读官方Harness文档、固定memory源码、durability示例与MIT许可。\n\n未公开或仍需目标环境验证的部分：特定模型能力组合；三域代表任务表现；采用存储的多实例一致性。本页不以产品表面行为推断其隐藏实现。\n\n[Pydantic AI：Harness能力边界](https://pydantic.dev/docs/ai/harness/)；[Pydantic AI：Memory scope与注入源码](https://github.com/pydantic/pydantic-ai/blob/f2d82f53873eb94614c23108b2045748b9c72252/src/pydantic_ai_harness/pydantic_ai_harness/memory/_capability.py#L33-L108)；[Pydantic AI：Durability集成](https://github.com/pydantic/pydantic-ai/blob/f2d82f53873eb94614c23108b2045748b9c72252/README.md#L120-L155)；[Pydantic AI：MIT许可](https://github.com/pydantic/pydantic-ai/blob/f2d82f53873eb94614c23108b2045748b9c72252/LICENSE)。",
      "blueprint": {
        "inputs": [
          "类型化任务和输出",
          "运行时依赖与工具",
          "Provider及durability后端"
        ],
        "steps": [
          "配置Agent与capabilities",
          "注入受限依赖和memory scope",
          "运行工具循环",
          "验证产物与恢复边界"
        ],
        "outputs": [
          "类型化领域产物",
          "能力和版本轨迹",
          "可比较主runtime方案"
        ]
      },
      "citations": [
        {
          "url": "https://pydantic.dev/docs/ai/harness/",
          "label": "Pydantic AI：Harness能力边界",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/pydantic/pydantic-ai/blob/f2d82f53873eb94614c23108b2045748b9c72252/src/pydantic_ai_harness/pydantic_ai_harness/memory/_capability.py#L33-L108",
          "label": "Pydantic AI：Memory scope与注入源码",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/pydantic/pydantic-ai/blob/f2d82f53873eb94614c23108b2045748b9c72252/README.md#L120-L155",
          "label": "Pydantic AI：Durability集成",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/pydantic/pydantic-ai/blob/f2d82f53873eb94614c23108b2045748b9c72252/LICENSE",
          "label": "Pydantic AI：MIT许可",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": [
        {
          "target": "structured-output",
          "type": "implements",
          "reason": "公开能力或可见源码体现结构化输出的具体产品路线。"
        },
        {
          "target": "model-adapter",
          "type": "complements",
          "reason": "用模型适配层检查采用时的控制边界；不推断未公开内部机制。"
        },
        {
          "target": "context-compaction",
          "type": "implements",
          "reason": "公开能力或可见源码体现上下文压缩的具体产品路线。"
        },
        {
          "target": "checkpoint-recovery",
          "type": "complements",
          "reason": "用Checkpoint与恢复检查采用时的控制边界；不推断未公开内部机制。"
        },
        {
          "target": "child-agent-contract",
          "type": "implements",
          "reason": "公开能力或可见源码体现子Agent委派合同的具体产品路线。"
        }
      ],
      "productRoute": {
        "vendor": "Pydantic",
        "category": "Typed Agent Runtime与Harness",
        "execution": "在应用选择的Python运行环境执行；持久后端按需接入。",
        "orchestration": "Typed loop配capabilities；可接现有durable execution引擎。",
        "context": "Typed core与Harness capabilities组合；记忆以受限背景注入并按需读取。",
        "persistence": "源码把memory作为背景而非指令；namespace由运行时提供并限制注入规模；默认内存store非持久后端。",
        "modelBoundary": "支持多provider；模型字符串可换不代表每个capability跨厂商行为相同。",
        "deployment": "云端API服务、worker或所选持久执行平台。",
        "license": "MIT",
        "availability": "观察于2026-10-15：具体capability和接口成熟度按文档逐项核实；v2.56.0；SHA f2d82f53873eb94614c23108b2045748b9c72252",
        "strengths": "强类型、依赖注入与多provider边界适合维护领域工具及开放模型路线。",
        "limits": "待验证或未公开：特定模型能力组合；三域代表任务表现；采用存储的多实例一致性。公开能力不等同企业负载与领域任务实测。"
      }
    },
    {
      "id": "retrieval-pipeline",
      "title": "查询与排名管线",
      "aliases": [],
      "kind": "branch",
      "parentId": "retrieval",
      "order": 20,
      "summary": "查询处理保留精确条件，词法和向量提供不同候选，融合解决跨路排序，rerank再投入更细的相关性判断。",
      "question": "查询与排名如何分工？",
      "body": "查询处理保留精确条件，词法和向量提供不同候选，融合解决跨路排序，rerank再投入更细的相关性判断。每一步都应保留输入与结果，以便定位证据在哪一层丢失。\n\n这一组页面依次回答为什么改写、怎样使用BM25、如何选择embedding、如何融合、何时重排。顺序是一个工程基线，不是所有问题必须付出的固定成本；精确查询可以走更短路线，复杂问题再采用完整管线。",
      "blueprint": {
        "inputs": [
          "任务问题与可用资料"
        ],
        "steps": [
          "查询处理保留精确条件，词法和向量提供不同候选，融合解决跨路排序，rerank再投入更细的相关性判断",
          "沿子节点选择合适机制"
        ],
        "outputs": [
          "可验证的检索设计选择"
        ]
      },
      "citations": [
        {
          "url": "https://docs.vespa.ai/en/learn/tutorials/hybrid-search",
          "label": "官方机制与实现参考",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "retrieval-result-cache",
      "title": "检索结果缓存",
      "en": "Retrieval Result Cache",
      "aliases": [
        "检索缓存",
        "候选证据缓存"
      ],
      "kind": "concept",
      "parentId": "performance-cache",
      "order": 20,
      "summary": "复用相同查询条件下的候选证据结果。",
      "question": "怎样设计检索结果缓存，并验证其对任务质量与可靠性的影响？",
      "body": "复用相同查询条件下的候选证据结果。\n\n检索结果缓存复用候选证据，不应直接复用授权结论。相同自然语言查询在不同用户、项目、日期和资料版本下可能有不同合法结果。企业先定义查询的业务条件，再决定哪些请求能够共享结果；不能只用query字符串或embedding相似度作键。\n\n建议缓存键包括规范化query、tenant、授权集合或策略版本、corpus/index generation、as_of以及检索参数。查询重写和过滤条件也会影响结果，应记录版本。缓存返回source_version与定位，最终原文读取仍重新鉴权，避免权限变化和删除传播的竞态。\n\n公开工具安全原则支持在真实数据访问点核验身份与scope；这里的缓存方案是企业设计建议，并非某个框架自动提供。共享缓存可以减少检索负载，但跨用户共享需要证明权限条件一致。即使候选正文不返回，标题、片段和文档存在性也可能泄漏，因此候选与rerank阶段同样受范围约束。\n\n失效不仅靠TTL。源更新、删除、ACL与群组变化、索引切换及时间窗口变化都要触发依赖失效。对于已进入context或摘要的旧证据，应使相关在途Run重建输入并复核待发布产物。清掉缓存后继续使用旧摘要，仍可能输出失去授权的内容。\n\n可以先缓存低风险、稳定公共资料，并对高风险或动态权限任务关闭共享。缓存粒度需平衡成本：过细键降低命中，过宽键增加陈旧与隔离错误。不要为了命中率牺牲业务边界。\n\n测试同一query由不同角色请求，随后撤销一份文档、更新一家公司期间、切换索引generation。检查候选、片段、rerank输入、最终引用与日志都符合当前权限。报告有效命中、陈旧结果与跨scope错误，而不只报告Redis hit rate。\n\n**实践重点**：键绑定tenant、授权版本、corpus/index generation、as_of和参数；读出再鉴权。\n\n**验证抓手**：用源更新、删除和ACL变化测试结果失效。\n\n**常见误区**：相似query跨用户共享，或权限撤回后仍命中。\n\n[MCP：安全建议](https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices)；[Anthropic：Context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)。\n\n检索缓存还应保留被排除结果的安全统计，帮助判断低召回来自数据不足还是权限过滤，但不记录越权正文或可识别片段。",
      "blueprint": {
        "inputs": [
          "规范化查询和as_of",
          "当前授权版本",
          "Corpus与索引generation"
        ],
        "steps": [
          "构造完整查询键",
          "读取缓存并重验scope",
          "追踪来源依赖",
          "更新或撤回时失效"
        ],
        "outputs": [
          "合法候选证据",
          "缓存依赖记录",
          "有效命中与隔离指标"
        ]
      },
      "citations": [
        {
          "url": "https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices",
          "label": "MCP：安全建议",
          "kind": "standard",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents",
          "label": "Anthropic：Context engineering",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "tool-authorization",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具授权网关。"
        },
        {
          "target": "cache-invalidation",
          "type": "requires",
          "reason": "本节点的设计需要先明确缓存依赖失效。"
        }
      ]
    },
    {
      "id": "runtime",
      "title": "运行时与工具",
      "en": "Runtime and Tools",
      "aliases": [],
      "kind": "domain",
      "parentId": null,
      "order": 20,
      "summary": "把目标变成可恢复、受授权且能验收的行动。",
      "question": "怎样从运行时与工具进入可实施的设计与验证？",
      "body": "运行时不是一个无限调用模型的循环。它需要识别任务、会话和执行尝试，组织工具、处理人工等待，并在网络失败或进程重启后知道哪些工作已经完成。模型选择下一步，工具网关决定能否执行，验证器判断业务结果，这三项责任应有明确边界。\n\n本分支从Harness与循环进入任务和恢复，再讨论委派与工具协议。公开源码用于理解可见实现，企业Task、权限和证据合同则是应用设计。初期可以用模块化单体实现，只有负载或安全边界需要时再拆服务。观察基线为2026-10-15；本文的设计建议不代表任一框架已通过企业负载验证。\n\n优先检查预写操作身份、外部幂等、取消、结果未知与恢复。一个页面能持续生成文字，不说明外部动作可靠；一个检查点能被加载，也不说明工具没有重复生效。\n\n[OpenAI：Agent运行时选择](https://developers.openai.com/api/docs/guides/agents)；[Claude Code：工作原理](https://code.claude.com/docs/en/how-claude-code-works)。",
      "blueprint": {
        "inputs": [
          "Task合同",
          "能力与权限",
          "模型和执行资源"
        ],
        "steps": [
          "明确决策、授权与验证",
          "建立任务和事件状态",
          "在受控边界调用工具",
          "故障与取消后核对效果"
        ],
        "outputs": [
          "可恢复Agent执行",
          "可追溯工具操作",
          "经过验收的产物"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/agents",
          "label": "OpenAI：Agent运行时选择",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://code.claude.com/docs/en/how-claude-code-works",
          "label": "Claude Code：工作原理",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": []
    },
    {
      "id": "runtime-task-session",
      "title": "任务、会话与恢复",
      "en": "Tasks Sessions and Recovery",
      "aliases": [],
      "kind": "branch",
      "parentId": "runtime",
      "order": 20,
      "summary": "用不同身份表达能力、交互、工作目标和执行状态。",
      "question": "怎样从任务、会话与恢复进入可实施的设计与验证？",
      "body": "会话连续性、业务任务和执行恢复不是同一项能力。把定义、部署、Session、Task、Run和操作身份分开，才能处理跨设备继续、后台任务、审批和重试。恢复的核心是知道已发生的效果，而非让模型从一段总结重新猜测。所有动态权限在继续执行时仍需核验。\n\n[Agents SDK：Session接口源码](https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/memory/session.py#L53-L94)；[LangGraph：Checkpointer与Store](https://docs.langchain.com/oss/python/langgraph/persistence)。",
      "blueprint": {
        "inputs": [
          "任务和参与者",
          "事件与工具回执"
        ],
        "steps": [
          "区分身份与状态",
          "提交恢复边界",
          "等待或重新调度",
          "核查取消和批准"
        ],
        "outputs": [
          "连续交互",
          "持久工作状态",
          "操作审计"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/memory/session.py#L53-L94",
          "label": "Agents SDK：Session接口源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        },
        {
          "url": "https://docs.langchain.com/oss/python/langgraph/persistence",
          "label": "LangGraph：Checkpointer与Store",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": []
    },
    {
      "id": "storage-architecture",
      "title": "数据层分工",
      "aliases": [],
      "kind": "branch",
      "parentId": "storage",
      "order": 20,
      "summary": "架构层给数据分配权威性与恢复来源。",
      "question": "系统真相、原件与加速层怎样分工？",
      "body": "架构层给数据分配权威性与恢复来源。事务状态、对象原件、缓存和检索派生物可以使用不同引擎，但必须明确修改由谁确认、索引落后如何发现、删除怎样传播。\n\n本组从权威与派生区分开始，再解释对象引用、临时协调及outbox。重点不是增加组件，而是防止某份摘要、缓存或向量payload悄悄成为唯一事实来源。",
      "blueprint": {
        "inputs": [
          "数据与运行要求"
        ],
        "steps": [
          "明确该层职责与约束",
          "按子节点比较并验证"
        ],
        "outputs": [
          "可追溯的数据层决定"
        ]
      },
      "citations": [
        {
          "url": "https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html",
          "label": "官方机制与实现参考",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "tool-discovery",
      "title": "工具发现与延迟加载",
      "en": "Tool Discovery",
      "aliases": [
        "Tool Search",
        "延迟加载"
      ],
      "kind": "concept",
      "parentId": "runtime-tools",
      "order": 20,
      "summary": "按任务发现工具，必要时才把完整定义放进上下文。",
      "question": "工具很多时，怎样只暴露当前合法且相关的能力？",
      "body": "按任务发现工具，必要时才把完整定义放进上下文。\n\n当企业接入数百个工具时，全量定义会占据上下文，也增加模型选错能力的机会。工具发现先根据当前任务和授权缩小目录，再按需要加载完整schema。它优化的是能力选择与输入占用，不是绕过审批的捷径。\n\nAnthropic公开advanced tool use与Claude Agent SDK文档介绍了tool search和延迟加载。不同模型及提供商对这一机制支持不同；不支持时需要可控的静态子集或应用路由，不能让模型在不知道接口的情况下猜参数。工具名称、描述和版本本身也是需要管理的资产。\n\n检索目录必须先受权限过滤。模型发现一个无权调用的工具，即使执行层最终拒绝，也可能暴露业务能力和资源信息。加载后的schema应冻结到当前step，与执行器使用同一版本。权限变化从下一个合法边界生效，并记录原因；资料里的“请加载管理工具”不是授权。\n\n发现质量可用正确工具是否进入候选、最终选错率、额外发现轮次与context成本评测。频繁改变工具定义还会影响prefix cache，因此不能只看减少了多少token。测试同义名称、相近职责、已下线版本和隐藏工具，检查模型是否能恢复；将发现失败与工具执行失败分开归因，才知道该改目录说明、检索方式还是模型。\n\n目录维护应包含工具owner、下线时间和替代接口。旧会话恢复时，如果原工具版本已经不可用，要选择显式迁移、重新规划或停止，不能把新接口悄悄套在旧参数上。对关键业务工具可保留兼容版本完成在途任务，并用真实恢复样例检查升级路径。\n\n发现服务的结果应带工具ID和版本，而非只返回自然语言名称。缓存目录时同样绑定授权代次，避免旧角色撤销后仍暴露原能力清单。\n\n**实践重点**：先缩小授权能力目录，再按语义发现并加载当前版本。\n\n**验证抓手**：测发现召回、错误工具率、context占用和cache变化。\n\n**常见误区**：延迟加载时遗漏权限检查，或每步改变工具定义破坏缓存。\n\n[Anthropic：Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use)；[Claude Agent SDK：概览](https://code.claude.com/docs/en/agent-sdk/overview)。",
      "blueprint": {
        "inputs": [
          "受授权工具目录",
          "当前Task意图",
          "模型tool-search能力"
        ],
        "steps": [
          "过滤权限和版本",
          "发现相关工具",
          "延迟加载完整schema",
          "冻结并执行当前step"
        ],
        "outputs": [
          "小规模工具集",
          "发现与加载记录",
          "可替代静态路由"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/advanced-tool-use",
          "label": "Anthropic：Advanced tool use",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://code.claude.com/docs/en/agent-sdk/overview",
          "label": "Claude Agent SDK：概览",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": [
        {
          "target": "tool-contract",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具接口合同。"
        },
        {
          "target": "tool-authorization",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具授权网关。"
        }
      ]
    },
    {
      "id": "eval-release-rollback",
      "title": "完整AgentRelease与状态回滚",
      "aliases": [
        "发布",
        "回滚",
        "补偿"
      ],
      "kind": "concept",
      "parentId": "evaluation-release",
      "order": 21,
      "summary": "以完整配置组合晋升和回滚，并单独处理已经写入的memory、业务状态和外部动作。",
      "question": "模型配置回退后，已写的记忆和业务状态怎样处理？",
      "body": "## 发布单位应是AgentRelease\n将runtime、模型snapshot、prompt、工具schema、workflow、skill、memory策略、检索策略、verifier和执行镜像视为一个版本组合。发布指针由受信控制平面维护，生产Agent可以提出diff，但不能自己扩大权限、修改隐藏测试或切换正式指针。每次run绑定所用release，再记录动态数据、索引generation与授权版本。\n\n## 晋升依据需要兼容性和新收益\n候选应说明目标能力、适用范围、前置条件和禁用条件。离线持出展示收益，回归保护已承诺行为，专家抽审核高风险标准，canary观察真实完成及成本。不能用一种领域总分抵消另一种领域的重大退化；也不能因为训练已经花钱，就忽略更差的上线结果。\n\n## 配置回退与状态回退分开\n恢复旧模型和prompt，只恢复后续执行策略。新版本已经写入的memory、业务记录、产物与外部动作仍存在。memory patch附来源和可撤销版本，业务写入保留稳定操作ID、前后值和外部receipt；不可逆动作预先约定人工处置或补偿。补偿本身也会失败，不能宣传一键回到世界原状。\n\n## 验证退出路径\n演练候选中途取消、供应商故障、schema升级、旧adapter重新加载、索引切换和权限撤回。确认旧版本能读取保留状态，或能明确拒绝不兼容状态并进入人工队列。发布后持续跑sentinel cases和新数据fresh audit，观察漂移。完整版本记录支持追责与比较，但固定配置不能成为继续使用已撤回权限的理由；执行与交付时仍需实时鉴权。\n\n## 回退是一条需要演练的业务路径\n准备旧版本仍能读取的新数据，以及必须迁移或隔离的新字段，演练发布后中途失败。回到旧模型并不会撤销已发送的文件，也不会自动修复被覆盖的偏好；分别记录补偿、人工通知和无法撤回的影响。发布指针、记忆patch、业务动作和回执要能互相追溯。回滚完成后重新验证用户可见终态，不能只看到配置值恢复就宣布业务已恢复。",
      "blueprint": {
        "inputs": [
          "完整release manifest",
          "配置数据memory版本",
          "可逆和补偿合同"
        ],
        "steps": [
          "核组合兼容和资格",
          "原子切换发布指针",
          "回退配置并检查已写状态",
          "补偿后重新验证"
        ],
        "outputs": [
          "发布与回退记录",
          "残留影响及未完成补偿"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/cookbook/examples/agents_sdk/agent_improvement_loop",
          "label": "OpenAI：Agent improvement loop",
          "kind": "official-doc",
          "note": "公开示例；本页发布合同为工程设计建议。"
        }
      ],
      "links": [
        {
          "target": "eval-canary",
          "type": "requires",
          "reason": "线上资格与退化信号决定晋升。"
        },
        {
          "target": "release-manifest",
          "type": "requires",
          "reason": "完整发布组合是追溯与回退的基础。"
        },
        {
          "target": "checkpoint-recovery",
          "type": "verifies",
          "reason": "回退资格包含检查点恢复后外部状态的一致性。"
        }
      ],
      "en": "Release and Rollback"
    },
    {
      "id": "agent-workflow",
      "title": "Workflow与局部Agent",
      "en": "Agentic Workflow",
      "aliases": [
        "工作流与Agent",
        "状态图"
      ],
      "kind": "concept",
      "parentId": "runtime-harness",
      "order": 30,
      "summary": "代码控制合法阶段，模型在阶段内选择探索路径。",
      "question": "哪些步骤由代码控制，哪些探索交给Agent？",
      "body": "代码控制合法阶段，模型在阶段内选择探索路径。\n\nWorkflow与Agent解决不同的不确定性。付款审批、文书发布、正式成绩更新等流程，有可明确描述的合法阶段；调查原因、寻找反证或选择下一篇资料，则往往要在执行中决定。把稳定业务骨架放在工作流，把探索放在局部Agent，可以同时获得灵活性与控制。\n\nAnthropic的经典模式区分预定义路径和模型控制路径；这是一种设计视角，不是要求购买某个框架。LangGraph的interrupt提供等待外部输入的机制，但恢复时包含interrupt的node会从头运行。因此一个写了“先发邮件，再等待批准”的节点，恢复时可能重复发送。审批点的位置、节点粒度和幂等边界必须一起设计。\n\n先画出业务状态而不是模型角色：证据收集、计算、复核、待批准、发布。每条转换都应写明输入、后置条件、允许副作用和失败去向。只有当流程进入“证据收集”时，Agent才在允许来源内自主检索。法律研究发现管辖信息不足，可以返回待输入；不能为了走到发布节点而补造法域。金融计算未通过单位和期间校验，应回到修正阶段。\n\n不必为所有问答引入重型状态图。短小只读任务可以直接循环；跨天审批和昂贵副作用更需要持久执行。若把外层Temporal与内层图组合，必须明确各自状态与重试权威，避免同一个动作被两层独立重放。验证应分别测阶段转换与节点内容质量：流程走得通，不能证明研究结论正确。\n\n实施时还应为每个阶段明确失败去向。例如证据不足可回到收集，计算错误可回到计算，审批拒绝则结束对应动作；不能把所有失败统一跳到重新开始。图越大越需要维护成本，只有能解释业务约束或可靠性收益的节点才值得存在。节点边界应能对照实际产物和事件，而非对应每一句模型思考。\n\n**实践重点**：审批、发布和业务约束用确定性转换；搜索与分析保留模型自由度。\n\n**验证抓手**：分别验证阶段转换合法性和节点内任务质量。\n\n**常见误区**：把所有任务硬编码成图，或把全部业务规则交给模型。\n\n[Anthropic：Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)；[LangGraph：Interrupt与恢复语义](https://docs.langchain.com/oss/python/langgraph/interrupts)。",
      "blueprint": {
        "inputs": [
          "业务阶段和转换规则",
          "局部探索任务",
          "审批与副作用要求"
        ],
        "steps": [
          "定义确定性阶段",
          "在阶段内调用Agent",
          "持久保存等待点",
          "验证转换和内容质量"
        ],
        "outputs": [
          "可恢复工作流",
          "局部Agent产物",
          "批准与发布记录"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/building-effective-agents",
          "label": "Anthropic：Building effective agents",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://docs.langchain.com/oss/python/langgraph/interrupts",
          "label": "LangGraph：Interrupt与恢复语义",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": [
        {
          "target": "agent-loop",
          "type": "requires",
          "reason": "本节点的设计需要先明确Agent执行循环。"
        },
        {
          "target": "business-task",
          "type": "requires",
          "reason": "本节点的设计需要先明确业务Task。"
        }
      ]
    },
    {
      "id": "business-task",
      "title": "业务Task",
      "en": "Business Task",
      "aliases": [
        "任务合同",
        "工作项"
      ],
      "kind": "concept",
      "parentId": "runtime-task-session",
      "order": 30,
      "summary": "持有业务生命周期的稳定工作身份，连接交互、执行尝试与最终产物。",
      "question": "同一业务工作跨Session、多次Run与重试时，怎样保持清楚的状态？",
      "body": "Task是业务工作持续存在的身份，Session是交互容器，Run是某次执行尝试。任务输入、动作范围和验收规则在[任务合同](/agent-framework/task-contract/)中统一定义；本页关注这份合同确认之后，工作如何跨会话、重试和人工等待保持一致状态。\n\n同一个Task可以由多个Session查询，也可以先后产生多个Run。用户换设备或新开聊天，不应自动创建重复业务工作；另一位参与者继续处理时则必须重新鉴权。关闭Session只结束交互，不等同取消后台Task。删除聊天、删除产物和撤回记忆也应依据各自策略执行，不能用一个按钮含混处理所有对象。\n\nTask的主要状态可以包括draft、queued、running、waiting_input、waiting_approval、verifying、succeeded、failed和cancelled。短暂网络错误与retrying更适合放在Run或Attempt，避免业务任务每遇到一次429就在成功失败之间反复跳转。每次转换保存原因和事件来源，让用户知道等待的具体对象。\n\n模型返回结果候选后，Task进入verifying；只有规定验证通过后才succeeded。工具返回accepted只说明动作被接收，不应直接使Task成功；外部操作unknown时，任务需要等待对账或明确部分结果。取消阻止新行动，却不自动撤销已发生效果，因此最终状态应保留已完成和仍未知的操作。\n\nRun绑定执行版本、预算和checkpoint，Task持有长期业务状态及最终产物。一个Run因基础设施故障恢复，通常不改变业务动作身份；如果用户实质修改目标或验收，则记录合同新版本并决定重开Run。Task ID、Run ID和operation_id分别服务工作归属、执行归因与副作用去重，不能互相替代。\n\n队列消息至少一次投递时，Task领取和状态更新需要事务、版本或租约控制。旧worker的结果不能覆盖新owner已经确认的状态。事件回放应从已提交意图、回执和验证重建进度，不从模型自然语言推断事实。任务清单可以展示当前owner、等待原因、已验证进展和产物，而无需暴露私有思维链。\n\n验证重点是生命周期：重复创建请求是否去重，换Session能否继续且不会扩权，worker重启是否复用正确Run，审批或deadline变化是否正确阻止旧工作，最终成功能否回到验收记录。只有这些映射稳定，平台才可以安全增加模型、子Agent或执行入口。\n\n[OpenAI托管架构中的应用与执行边界](https://developers.openai.com/api/docs/guides/agents-api/architecture)；[长期任务的持久产物与增量工作](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)。",
      "blueprint": {
        "inputs": [
          "已确认Task合同",
          "当前Session及授权",
          "现有Run和操作状态"
        ],
        "steps": [
          "定位稳定Task身份",
          "按事件转换业务状态",
          "关联恢复或新Run",
          "验证后提交最终产物"
        ],
        "outputs": [
          "业务生命周期",
          "Session与Run映射",
          "可核查最终状态"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/agents-api/architecture",
          "label": "OpenAI：托管Agents架构",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents",
          "label": "Anthropic：长期任务Harness",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": [
        {
          "target": "task-contract",
          "type": "requires",
          "reason": "任务输入、范围和验收以唯一任务合同节点为准；本页只展开生命周期。"
        }
      ]
    },
    {
      "id": "context-assembly",
      "title": "上下文组装",
      "en": "Context Assembly",
      "aliases": [
        "Context Engineering",
        "上下文工程"
      ],
      "kind": "concept",
      "parentId": "models-context",
      "order": 30,
      "summary": "为当前模型调用选择规则、状态、证据、历史与工具说明。",
      "question": "怎样设计上下文组装，并验证其对任务质量与可靠性的影响？",
      "body": "为当前模型调用选择规则、状态、证据、历史与工具说明。\n\n模型每次调用看到的是经过选择的输入，不是企业全部知识。context builder决定放入哪些应用规则、任务限制、当前状态、近期交互、证据、工具说明和相关记忆。context engineering的目标是提高有效信息密度，并保持来源与信任边界，而不是把窗口填满。\n\n推荐先明确当前step要解决的问题，再按用途分配预算。稳定应用规则和工具定义适合靠前，用户最新修订、动态证据与工具结果按任务选择；不同模型仍需独立测顺序与预算。重要限制不能因更早出现而被丢弃，外部文档中的指令不能被提升为应用规则。长上下文是容量，不等于所有位置都能同等准确利用。\n\nCodex公开源码在step边界捕获context与工具视图，避免模型可见定义和执行器不一致。Pydantic Harness的memory实现把记忆作为背景信息注入，并对规模和scope加限制。借鉴这些边界时，企业可把当前授权、Task合同和操作状态从结构化系统生成；自由文本摘要只负责补充历史，不承担权威控制。\n\n工具返回过长时，原始对象外置，只注入摘要、定位和可再读取引用；数值与表格保留单位、期间和公式来源。对话历史可以选择近期原文并压缩更早部分，但要保留未决审批、用户否定条件和已发生副作用。相关性与重要性不同，一条“不发送给客户”的短限制可能比十页资料更重要。\n\n验证应包含长文中的关键事实、早期用户限制、冲突材料和权限撤回。检查模型能否定位支持与反证，以及删除某块context后结果怎样变化。输入快照可保存引用和加密payload，不必把敏感全文复制进全局trace。若只记录总token数，就无法判断质量变化来自资料选择、顺序、压缩还是模型本身。\n\n一个实用方法是让每块输入带用途与来源：规则、任务状态、外部证据和历史观察。它帮助应用审计，也方便做消融。标签有助结构化，但不是安全隔离；执行权限仍由工具网关决定。\n\n**实践重点**：稳定规则前置，动态信息按相关性和预算选择；保存版本和引用。\n\n**验证抓手**：测试关键限制、否定条件和引用在长任务中是否保留。\n\n**常见误区**：把全部历史和文档塞满窗口，或混淆资料与高优先级指令。\n\n[Anthropic：Context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)；[Codex：turn与step循环源码](https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/turn.rs#L454-L518)。\n\n[Pydantic Harness memory的直接源码依据](https://github.com/pydantic/pydantic-ai/blob/f2d82f53873eb94614c23108b2045748b9c72252/src/pydantic_ai_harness/pydantic_ai_harness/memory/_capability.py#L33-L108)。",
      "blueprint": {
        "inputs": [
          "当前Step问题",
          "Task状态和授权",
          "可用证据、历史及记忆"
        ],
        "steps": [
          "按用途选择信息",
          "保留关键约束与来源",
          "限制长工具输出",
          "记录输入视图和版本"
        ],
        "outputs": [
          "本步模型输入",
          "证据与历史引用",
          "Context预算及取舍"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents",
          "label": "Anthropic：Context engineering",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/turn.rs#L454-L518",
          "label": "Codex：turn与step循环源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://github.com/pydantic/pydantic-ai/blob/f2d82f53873eb94614c23108b2045748b9c72252/src/pydantic_ai_harness/pydantic_ai_harness/memory/_capability.py#L33-L108",
          "label": "Pydantic AI：Memory背景注入、scope与规模约束",
          "kind": "code",
          "locator": "_capability.py:33–108",
          "note": "固定SHA；对应本文关于memory作为背景与运行时scope的源码描述。"
        }
      ],
      "links": [
        {
          "target": "model-capability-registry",
          "type": "requires",
          "reason": "本节点的设计需要先明确模型能力注册。"
        },
        {
          "target": "tool-contract",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具接口合同。"
        }
      ]
    },
    {
      "id": "dify",
      "title": "Dify",
      "en": "Dify",
      "aliases": [
        "Dify Platform"
      ],
      "kind": "product",
      "parentId": "products-platforms",
      "order": 30,
      "summary": "面向AI应用与可视化流程的完整平台。",
      "question": "它怎样运行Agent，哪些状态和权限仍由应用负责？",
      "body": "观察时点：2026-10-15。面向AI应用与可视化流程的完整平台。\n\n## 已公开的技术路线与控制边界\n\n平台式应用、知识与workflow配置，优先通过服务与扩展接口复用。平台管理应用流程和工作区；企业仍定义数据许可、领域验收和高风险动作授权。\n\nDify属于完整AI应用平台，比较对象与单一runtime库不同。它把应用配置、工作流、知识和操作界面组合起来，有助快速验证内部场景。企业首先考虑配置、API和扩展边界，而非为了定制品牌直接fork全部代码。\n\n平台式路线可以减少基础管理界面和流程搭建工作，但业务Task、法律matter、学生身份和投研证据仍需要明确合同。可视化画布显示一条路径能够执行，不代表权限、来源更新、幂等和领域质量已经通过。关键动作必须对应实际工具与数据层控制。\n\n知识和会话位于平台自己的数据模型中。采用前检查原件、chunk、引用与权限的关系，以及源更新、删除和跨workspace访问如何传播。长期memory还要区分会话历史与经过验证的偏好或程序性技能，不能因为有持久聊天就认为已经具备完整记忆治理。\n\n模型连接能力也需要按实际版本和provider验证。相同工作流更换模型后，工具选择、输出schema、拒绝与错误处理可能变化。若用Dify快速探索前台用例，同时另有代码runtime负责核心任务，应明确恢复与发布权威，避免两套流程重复提交副作用。\n\n许可需要按具体使用方式审阅。本次固定LICENSE是修改版Apache-2.0，附加条件对多租户环境及使用其前端时的LOGO和版权信息作限制，并将tenant定义为workspace。不能把公开仓库或Apache字样理解为任意多客户白标都已获准。云服务与源码部署也不是同一合同。\n\n对本企业，更合理的首步可能是用现有平台跑一个权限明确、结果可核查的内部任务，对比自有控制平面方案的改造与维护成本。测试真实ACL、源撤回、审批重放、任务恢复和数据导出，再决定哪些部分继续配置、通过API集成或自行实现。README与许可证据只能支持进入验证，不能证明生产采用门槛已通过。\n\n首个金融用例可只接公开财报与只读计算，要求每个数字能回到原件；首个教育用例可以限定一个课程与测试学生；法律用例先用非敏感合同样本。平台把流程跑通后，再增加真实身份和数据，检查不同用户能否看见不同证据。若关键权限需要重写平台核心数据模型，改造和升级成本可能超过接口集成收益，应重新比较路线。选择云服务可以减少运维，但仍要保留来源、评测和业务产物的导出能力。\n\n## 数据、记忆与模型替换\n\n知识、会话与workspace具有平台数据模型；对删除、导出和训练使用另核合同。\n\n连接不同模型不等于每模型质量与工具行为等价。\n\n## 执行、部署与采用取舍\n\n平台服务执行配置的应用流程，工具和外部系统各有责任。可视化workflow与Agent能力；核心业务约束仍需明确实现。Dify云服务或符合许可的源码部署；合同和能力分别核验。\n\n完整平台有利于快速验证内部应用；优先配置和接口集成。\n\n观察于2026-10-15：云服务与自托管源码按具体产品合同区分；latest non-prerelease 1.17.1；SHA 310ce87f9d78313966e5d17753ad36b9725b280b\n\n许可边界：修改版Apache-2.0，含附加条件。采用前按实际使用方式核验组件、云服务与模型条款。\n\n## 证据范围与未知\n\n固定仓库和LICENSE已核；许可附多租户及前端品牌条件。\n\n未公开或仍需目标环境验证的部分：企业三域质量；云版本权限和导出；具体使用方式许可适用性。本页不以产品表面行为推断其隐藏实现。\n\n[Dify：固定源码](https://github.com/langgenius/dify/tree/310ce87f9d78313966e5d17753ad36b9725b280b)；[Dify：附加许可条件](https://github.com/langgenius/dify/blob/310ce87f9d78313966e5d17753ad36b9725b280b/LICENSE)。",
      "blueprint": {
        "inputs": [
          "明确内部用例",
          "平台工作区与知识源",
          "模型及业务工具"
        ],
        "steps": [
          "配置应用和流程",
          "核验数据与许可边界",
          "运行代表任务",
          "比较导出和定制成本"
        ],
        "outputs": [
          "应用或工作流结果",
          "平台集成边界",
          "采用与许可待核事项"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/langgenius/dify/tree/310ce87f9d78313966e5d17753ad36b9725b280b",
          "label": "Dify：固定源码",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/langgenius/dify/blob/310ce87f9d78313966e5d17753ad36b9725b280b/LICENSE",
          "label": "Dify：附加许可条件",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": [
        {
          "target": "agent-workflow",
          "type": "implements",
          "reason": "公开能力或可见源码体现Workflow与局部Agent的具体产品路线。"
        },
        {
          "target": "business-task",
          "type": "implements",
          "reason": "公开能力或可见源码体现业务Task的具体产品路线。"
        },
        {
          "target": "tool-authorization",
          "type": "implements",
          "reason": "公开能力或可见源码体现工具授权网关的具体产品路线。"
        },
        {
          "target": "structured-output",
          "type": "implements",
          "reason": "公开能力或可见源码体现结构化输出的具体产品路线。"
        },
        {
          "target": "release-manifest",
          "type": "complements",
          "reason": "用运行版本清单检查采用时的控制边界；不推断未公开内部机制。"
        }
      ],
      "productRoute": {
        "vendor": "LangGenius",
        "category": "AI应用与工作流平台",
        "execution": "平台服务执行配置的应用流程，工具和外部系统各有责任。",
        "orchestration": "可视化workflow与Agent能力；核心业务约束仍需明确实现。",
        "context": "应用和流程节点组合指令、知识与模型输入；具体context与memory行为依配置核验。",
        "persistence": "知识、会话与workspace具有平台数据模型；对删除、导出和训练使用另核合同。",
        "modelBoundary": "连接不同模型不等于每模型质量与工具行为等价。",
        "deployment": "Dify云服务或符合许可的源码部署；合同和能力分别核验。",
        "license": "修改版Apache-2.0，含附加条件",
        "availability": "观察于2026-10-15：云服务与自托管源码按具体产品合同区分；latest non-prerelease 1.17.1；SHA 310ce87f9d78313966e5d17753ad36b9725b280b",
        "strengths": "完整平台有利于快速验证内部应用；优先配置和接口集成。",
        "limits": "待验证或未公开：企业三域质量；云版本权限和导出；具体使用方式许可适用性。公开能力不等同企业负载与领域任务实测。"
      }
    },
    {
      "id": "knowledge-lifecycle",
      "title": "版本、权限与撤回",
      "aliases": [
        "knowledge lifecycle"
      ],
      "kind": "branch",
      "parentId": "knowledge",
      "order": 30,
      "summary": "管理原件版本、活动发布、权限传播与全链路撤回。",
      "question": "怎样持续更新知识并可靠撤回旧内容？",
      "body": "知识库必须能够持续更新，也必须能够停止使用已经撤回的资料。来源、版本、活动状态和可见性因此是一组长期维护的数据合同，不能作为入库时的一次性标签。\n\n本组分别解释不可变版本与来源链、增量索引发布、权限传播和删除清理。内容更新通常允许保留上一完整版本，权限撤回与删除则应优先禁用。将这两类事件使用同一低优先级后台队列，容易让系统在最终一致窗口内继续展示不应提供的内容。",
      "blueprint": {
        "inputs": [
          "内容、权限与删除事件"
        ],
        "steps": [
          "建立版本与lineage",
          "发布完整活动版本",
          "优先传播撤回并对账"
        ],
        "outputs": [
          "可恢复且可撤回的知识状态"
        ]
      },
      "citations": [
        {
          "url": "https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html",
          "label": "AWS：跨系统事件一致性",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "langgraph",
      "title": "LangGraph",
      "en": "LangGraph",
      "aliases": [
        "LangGraph Runtime"
      ],
      "kind": "product",
      "parentId": "products-frameworks",
      "order": 30,
      "summary": "以显式图状态和checkpoint运行可中断、可恢复的Agent工作流。",
      "question": "它怎样运行Agent，哪些状态和权限仍由应用负责？",
      "body": "观察时点：2026-10-15。以显式图状态和checkpoint运行可中断、可恢复的Agent工作流。\n\n## 已公开的技术路线与控制边界\n\nPregel式并行task执行、writes提交、state channels、interrupt与checkpointer。框架维护图执行状态；业务授权、外部副作用和长期记忆合同由应用负责。\n\nLangGraph最核心的价值是显式状态与可恢复执行，而不只是把模型框起来画成图。固定源码的runner并行执行task，提交writes，并区分成功、错误、取消和GraphInterrupt；checkpoint记录channel值、版本及节点已见版本，为下一步调度提供依据。\n\n图适合表达稳定业务阶段：证据收集、计算、复核、待批准和发布。节点内可以让Agent自主选工具，但阶段转换、批准和发布由确定性规则控制。金融研究、合同辅助和教师审核等场景可能受益；普通只读问答未必需要复杂图，节点数量不是工程成熟度指标。\n\n官方明确区分checkpointer和Store。前者保存thread内图状态，支持继续、等待和时间旅行；后者保存跨thread应用数据。内存实现不跨重启持久，数据库后端又需要连接、迁移和保留治理。两者都不能自动替代业务事务、来源权限或有TTL与冲突处理的企业记忆。\n\nInterrupt的恢复语义必须理解：包含interrupt的node从头重跑，因此之前的代码也会再次执行。高风险副作用放在审批之后并使用稳定业务ID，或拆成独立边界。检查点存在不保证外部exactly-once；工具成功后持久化失败的间隙仍需read-back。\n\n若与Temporal等外层引擎组合，写清谁管理等待、业务重试和模型结果持久化。两个系统都试图“恢复到正确位置”而不了解对方，可能让关键决定重新生成或动作重复。初期优先选一个主权威，在明确边界内调用其他组件。\n\n采用成本包括graph/reducer设计、并行冲突、状态膨胀、checkpoint清理和schema升级。MIT许可利于集成，但托管服务和开源库的运行合同不同。验证要杀进程、重复回调、等待人工并升级代码，检查图状态、外部结果和最终验收一起成立。公开源码审阅不能被写成这些测试已经通过。\n\n一个合同辅助图可将研究、引证核验、律师review和发布分开。研究节点动态搜索，核验节点检查原文、版本和有效性，review使用持久等待；发布节点只接收与批准hash一致的产物。若等待期间合同或权限变化，恢复时重新核对，而非继续旧状态。可用同一任务的直接循环作对照，检查图是否减少非法转换和人工追踪成本。若图只增加形式而未改善恢复或验收，应缩小阶段粒度，不因已经画图就保留全部节点。\n\n## 数据、记忆与模型替换\n\nCheckpointer保存thread内图状态，Store保存跨thread应用数据；两者不同。\n\n图可调用不同provider；切换时仍需工具、schema和context契约测试。\n\n## 执行、部署与采用取舍\n\n图运行在应用或选定托管平台，实际工具由应用配置。Pregel式task执行、state channels、checkpoint与interrupt。开源库自运维或相应托管运行平台，合同分别核验。\n\n适合明确审批与阶段的长任务；显式状态便于故障和分支分析。\n\n观察于2026-10-15：当前包与子包release标签应分别识别；源码core包1.2.15；SHA 889a5ff16f8325113093d517dffd5471a943c760\n\n许可边界：MIT。采用前按实际使用方式核验组件、云服务与模型条款。\n\n## 证据范围与未知\n\n固定源码已读runner和checkpoint；官方说明interrupt恢复会从node开头重跑。\n\n未公开或仍需目标环境验证的部分：外部效果exactly-once；业务schema迁移；目标负载延迟与存储增长。本页不以产品表面行为推断其隐藏实现。\n\n[LangGraph：Checkpointer与Store](https://docs.langchain.com/oss/python/langgraph/persistence)；[LangGraph：Interrupt与恢复语义](https://docs.langchain.com/oss/python/langgraph/interrupts)；[LangGraph：Runner提交源码](https://github.com/langchain-ai/langgraph/blob/889a5ff16f8325113093d517dffd5471a943c760/libs/langgraph/langgraph/pregel/_runner.py#L575-L615)；[LangGraph：Checkpoint模型源码](https://github.com/langchain-ai/langgraph/blob/889a5ff16f8325113093d517dffd5471a943c760/libs/checkpoint/langgraph/checkpoint/base/__init__.py#L93-L123)；[LangGraph：MIT许可](https://github.com/langchain-ai/langgraph/blob/889a5ff16f8325113093d517dffd5471a943c760/LICENSE)。",
      "blueprint": {
        "inputs": [
          "业务状态图",
          "Thread和checkpoint配置",
          "工具与审批合同"
        ],
        "steps": [
          "编译阶段与状态规则",
          "执行并提交节点writes",
          "Interrupt等待和恢复",
          "外部效果及最终验收"
        ],
        "outputs": [
          "可恢复图状态",
          "阶段化领域产物",
          "完整失败和迁移记录"
        ]
      },
      "citations": [
        {
          "url": "https://docs.langchain.com/oss/python/langgraph/persistence",
          "label": "LangGraph：Checkpointer与Store",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://docs.langchain.com/oss/python/langgraph/interrupts",
          "label": "LangGraph：Interrupt与恢复语义",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/langchain-ai/langgraph/blob/889a5ff16f8325113093d517dffd5471a943c760/libs/langgraph/langgraph/pregel/_runner.py#L575-L615",
          "label": "LangGraph：Runner提交源码",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/langchain-ai/langgraph/blob/889a5ff16f8325113093d517dffd5471a943c760/libs/checkpoint/langgraph/checkpoint/base/__init__.py#L93-L123",
          "label": "LangGraph：Checkpoint模型源码",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/langchain-ai/langgraph/blob/889a5ff16f8325113093d517dffd5471a943c760/LICENSE",
          "label": "LangGraph：MIT许可",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": [
        {
          "target": "agent-workflow",
          "type": "implements",
          "reason": "公开能力或可见源码体现Workflow与局部Agent的具体产品路线。"
        },
        {
          "target": "checkpoint-recovery",
          "type": "complements",
          "reason": "用Checkpoint与恢复检查采用时的控制边界；不推断未公开内部机制。"
        },
        {
          "target": "human-approval",
          "type": "implements",
          "reason": "公开能力或可见源码体现人工审批合同的具体产品路线。"
        },
        {
          "target": "parallel-result-merge",
          "type": "implements",
          "reason": "公开能力或可见源码体现并行结果合并的具体产品路线。"
        },
        {
          "target": "idempotent-side-effects",
          "type": "complements",
          "reason": "用业务副作用幂等检查采用时的控制边界；不推断未公开内部机制。"
        }
      ],
      "productRoute": {
        "vendor": "LangChain",
        "category": "状态图与持久执行框架",
        "execution": "图运行在应用或选定托管平台，实际工具由应用配置。",
        "orchestration": "Pregel式task执行、state channels、checkpoint与interrupt。",
        "context": "图状态由checkpointer保存，模型context由节点和应用构造；Store另存跨thread数据。",
        "persistence": "Checkpointer保存thread内图状态，Store保存跨thread应用数据；两者不同。",
        "modelBoundary": "图可调用不同provider；切换时仍需工具、schema和context契约测试。",
        "deployment": "开源库自运维或相应托管运行平台，合同分别核验。",
        "license": "MIT",
        "availability": "观察于2026-10-15：当前包与子包release标签应分别识别；源码core包1.2.15；SHA 889a5ff16f8325113093d517dffd5471a943c760",
        "strengths": "适合明确审批与阶段的长任务；显式状态便于故障和分支分析。",
        "limits": "待验证或未公开：外部效果exactly-once；业务schema迁移；目标负载延迟与存储增长。公开能力不等同企业负载与领域任务实测。"
      }
    },
    {
      "id": "memory-representation",
      "title": "表示与召回",
      "aliases": [],
      "kind": "branch",
      "parentId": "memory",
      "order": 30,
      "summary": "小型profile或核心block适合少量稳定信息，大量事实和经历适合按任务召回。",
      "question": "哪些信息常驻，哪些按需取回？",
      "body": "小型profile或核心block适合少量稳定信息，大量事实和经历适合按任务召回。两种方式共享来源、scope与时间语义，却有不同token成本和过期风险。\n\n本组分别讨论常驻表示与召回策略，最后都向context assembly交付数据。它们不决定系统指令优先级，也不能让旧记忆绕过当前授权；是否常驻只是上下文选择，不是事实权威的提升。",
      "blueprint": {
        "inputs": [
          "记忆合同和任务需要"
        ],
        "steps": [
          "按子节点选择机制",
          "验证跨Session效果与边界"
        ],
        "outputs": [
          "可维护的记忆设计"
        ]
      },
      "citations": [
        {
          "url": "https://docs.letta.com/v1-sdk/memory/memory-blocks",
          "label": "官方机制与实现参考",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "meta-muse",
      "title": "Meta Muse",
      "en": "Meta Muse",
      "aliases": [
        "Muse",
        "Muse Wonder",
        "Muse Code"
      ],
      "kind": "product",
      "parentId": "products-personal",
      "order": 30,
      "summary": "将个人Agent、云端行动环境和连接服务组合的产品。",
      "question": "它怎样运行Agent，哪些状态和权限仍由应用负责？",
      "body": "观察时点：2026-10-15。将个人Agent、云端行动环境和连接服务组合的产品。\n\n## 已公开的技术路线与控制边界\n\n官方工程描述每用户Linux VM、runtime cell、cell外凭据服务与Sentinel及独立Postgres状态。Sentinel管connector动作和网络出口；VM内数据不代表推理或telemetry永不外发。\n\nMeta Muse需要同时区分个人Agent产品、Muse Code入口和Muse模型家族。模型API发布、订阅可用和个人产品切换不是同一个事件。企业研究不能因某个模型宣布推出，就写成所有个人Muse用户已经使用，也不能由Llama历史推断Muse模型权重与训练许可开放。\n\n官方个人产品发布描述移动app、网页和WhatsApp交互、后台任务与连接服务，并在敏感动作前确认。推出页提及的Confidential VM属于当时后续计划，不能当作首发已交付。观察日期和功能阶段是产品合同的一部分，后续采用应重新核验。\n\n公开安全工程描述每用户独立Linux VM，harness位于runtime cell内，凭据服务和权限Sentinel位于cell外，持久应用状态放在独立Postgres。Sentinel检查connector动作和网络出口。这是厂商公开架构说明，独立验证仍未知；但可借鉴把可生成代码环境与授权权威分开的原则。\n\n“数据在VM”并不等于所有推理本地运行或资料绝不离开环境。文章也说明推理和telemetry可能向外发送数据。企业即使完全上云，也需要单独核对模型推理、文件、日志、快照和训练用途的保留与区域合同，不能凭一个隔离盒子推断全部数据流。\n\n2026-10-12的模型公告描述Wonder经Meta Model API及Muse Code提供，Full经Muse Code订阅提供；Wonder进入个人产品仍有soon与分批条件。Active Memory、Focus和benchmark优势是厂商定义和自测，应与企业资料、工具及任务评测分开。未公开的内部memory数据库、完整harness源码和模型权重取得方式继续标未知。\n\n可学习的企业路线是每用户或租户隔离环境、独立权限网关与可信业务状态，再以真实外部回执检查动作。个人产品带来的便利不自动覆盖客户matter或班级隔离。采用前测试账号能力、动作确认、取消、数据导出和删除，并逐模型审查API、权重及微调许可，而不是把整个Muse品牌当一种统一技术组件。\n\n企业可以借鉴的最小切片，是将可执行环境、凭证、网络动作和权威状态分开：环境处理文件，网关持有短期授权，数据库记录Task与操作，外部verifier读回结果。即使模型被资料诱导，仍不能直接获得完整凭证。隔离粒度按用户、matter或租户风险选择，而不是照搬消费产品。测试应覆盖跨环境文件、连接权限撤回、敏感动作确认与网络出口。公开安全文章给出设计依据，不能证明任一企业接入方案天然具备同等安全性或模型可替换能力。\n\n## 数据、记忆与模型替换\n\n持久应用状态与行动环境分离；个人Muse产品、Muse Code和模型API不是同一资源。\n\nMuse Wonder/API发布不等于个人Muse已全面切换；也不证明权重或fine-tuning许可开放。\n\n## 执行、部署与采用取舍\n\n官方工程描述每用户Linux VM；授权与凭证服务在runtime cell外。个人Agent协调后台工作，Sentinel检查连接器动作与网络出口。美国逐步推出app与网页；Muse Code/API/模型可用性另列。\n\n公开安全边界有参考价值；模型、产品和计划功能必须分开判断。\n\n观察于2026-10-15：美国逐步推出；模型、产品、订阅与计划功能分别标状态。\n\n许可边界：商业产品及逐模型条款。采用前按实际使用方式核验组件、云服务与模型条款。\n\n## 证据范围与未知\n\n官方产品发布、安全工程与Wonder模型公告均可核；Confidential VM在初发页为后续计划。\n\n未公开或仍需目标环境验证的部分：完整harness源码；所有用户模型切换时间；权重取得及训练许可。本页不以产品表面行为推断其隐藏实现。\n\n[Meta：Muse个人Agent发布](https://about.fb.com/news/2026/09/introducing-muse-personal-ai-agent/)；[Meta：Muse安全工程设计](https://research.meta.ai/blog/security-and-safety-for-ai-agents-our-approach-with-muse)；[Meta：Muse Wonder模型发布](https://about.fb.com/news/2026/10/introducing-muse-wonder-models/)。",
      "blueprint": {
        "inputs": [
          "个人目标与获准连接",
          "隔离行动环境",
          "敏感动作确认与状态"
        ],
        "steps": [
          "通过产品入口协调任务",
          "在cell内执行行动",
          "由外部权限服务审查",
          "保存并反馈持久结果"
        ],
        "outputs": [
          "个人任务与产物",
          "动作确认及持久状态",
          "产品与模型边界"
        ]
      },
      "citations": [
        {
          "url": "https://about.fb.com/news/2026/09/introducing-muse-personal-ai-agent/",
          "label": "Meta：Muse个人Agent发布",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://research.meta.ai/blog/security-and-safety-for-ai-agents-our-approach-with-muse",
          "label": "Meta：Muse安全工程设计",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://about.fb.com/news/2026/10/introducing-muse-wonder-models/",
          "label": "Meta：Muse Wonder模型发布",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": [
        {
          "target": "sandbox-lifecycle",
          "type": "implements",
          "reason": "公开能力或可见源码体现沙箱生命周期的具体产品路线。"
        },
        {
          "target": "tool-authorization",
          "type": "implements",
          "reason": "公开能力或可见源码体现工具授权网关的具体产品路线。"
        },
        {
          "target": "agent-session",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent Session的具体产品路线。"
        },
        {
          "target": "model-adapter",
          "type": "complements",
          "reason": "用模型适配层检查采用时的控制边界；不推断未公开内部机制。"
        },
        {
          "target": "checkpoint-recovery",
          "type": "complements",
          "reason": "用Checkpoint与恢复检查采用时的控制边界；不推断未公开内部机制。"
        }
      ],
      "productRoute": {
        "vendor": "Meta",
        "category": "个人Agent与模型生态",
        "execution": "官方工程描述每用户Linux VM；授权与凭证服务在runtime cell外。",
        "orchestration": "个人Agent协调后台工作，Sentinel检查连接器动作与网络出口。",
        "context": "产品任务上下文与Muse模型家族能力分开；完整内部context组装未公开。",
        "persistence": "持久应用状态与行动环境分离；个人Muse产品、Muse Code和模型API不是同一资源。",
        "modelBoundary": "Muse Wonder/API发布不等于个人Muse已全面切换；也不证明权重或fine-tuning许可开放。",
        "deployment": "美国逐步推出app与网页；Muse Code/API/模型可用性另列。",
        "license": "商业产品及逐模型条款",
        "availability": "观察于2026-10-15：美国逐步推出；模型、产品、订阅与计划功能分别标状态。",
        "strengths": "公开安全边界有参考价值；模型、产品和计划功能必须分开判断。",
        "limits": "待验证或未公开：完整harness源码；所有用户模型切换时间；权重取得及训练许可。公开能力不等同企业负载与领域任务实测。"
      }
    },
    {
      "id": "model-upgrade-matrix",
      "title": "模型与Harness升级矩阵",
      "en": "Model Harness Upgrade Matrix",
      "aliases": [
        "升级矩阵",
        "模型回归"
      ],
      "kind": "concept",
      "parentId": "models-release",
      "order": 30,
      "summary": "通过交叉比较区分模型、harness及二者交互带来的变化。",
      "question": "怎样设计模型与Harness升级矩阵，并验证其对任务质量与可靠性的影响？",
      "body": "通过交叉比较区分模型、harness及二者交互带来的变化。\n\n模型升级可能改变工具选择、规划、schema行为、上下文利用和停止方式。新模型整体更强，不保证原Agent在所有任务上更强；旧harness中的强制短计划、频繁reset或冗余自评，可能限制新模型发挥。升级应比较模型与harness的交互，而非只跑一个新模型分数。\n\n最小矩阵包含旧模型配旧harness、新模型配旧harness、旧模型配新harness、新模型配新harness。这样可以分辨质量变化来自模型、外围工程还是组合。Prompt、工具、检索、memory政策和verifier都应记录版本；同时变太多因素会使根因不清。\n\n先通过协议契约测试，再做代表业务任务。前者检查工具call ID、stream、schema、拒绝和取消，后者检查证据、计算、权限与真实后置条件。对旧workaround进行消融：保留原规则、删除补丁和使用新默认设置分别比较，避免“更复杂”被当成“更可靠”。\n\n评测要保留未见样例和严重错误分类，单次最佳表现不能替代稳定性。上下文压缩、冷缓存和工具故障也应进入升级场景。主模型与judge同时升级时，评分变化可能来自评估器，因此需保持一条稳定校准路径。\n\n通过离线门槛后再shadow和canary。Shadow若有真实外部工具，必须禁用副作用或采用隔离后端；否则影子流量也可能重复发信或写入。回滚应恢复完整版本组合，而非只改model ID。\n\n公开模型目录和框架文档给出能力入口，具体企业任务必须自行验证。供应商未提供固定snapshot时，记录复现限制并持续跑哨兵样例。模型发布当天可以进入候选，不必自动成为生产默认。\n\n对于会执行外部动作的用例，升级实验需要测试后端或明确只读模式。重复跑同一评测，不应向真实客户重复发信或修改正式记录。评测隔离本身也是发布合同的一部分。\n\n**实践重点**：比较旧旧、新旧、旧新、新新；删除旧workaround做消融。\n\n**验证抓手**：先兼容性和离线任务，再shadow、canary与完整回滚。\n\n**常见误区**：更强模型上线后原Agent反而退化却无法归因。\n\n[Pydantic AI：Harness能力边界](https://pydantic.dev/docs/ai/harness/)；[OpenAI Agents SDK：模型与provider](https://developers.openai.com/api/docs/guides/agents/models)。",
      "blueprint": {
        "inputs": [
          "旧新模型与harness",
          "冻结业务任务集",
          "严重错误与成本门槛"
        ],
        "steps": [
          "运行交叉矩阵",
          "做协议与任务回归",
          "消融旧补丁",
          "Shadow和canary后发布"
        ],
        "outputs": [
          "可归因升级报告",
          "发布或拒绝决定",
          "完整回滚目标"
        ]
      },
      "citations": [
        {
          "url": "https://pydantic.dev/docs/ai/harness/",
          "label": "Pydantic AI：Harness能力边界",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://developers.openai.com/api/docs/guides/agents/models",
          "label": "OpenAI Agents SDK：模型与provider",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "model-adapter",
          "type": "requires",
          "reason": "本节点的设计需要先明确模型适配层。"
        },
        {
          "target": "agent-definition-version",
          "type": "requires",
          "reason": "本节点的设计需要先明确Agent定义与版本。"
        }
      ]
    },
    {
      "id": "models",
      "title": "模型、Prompt与适配",
      "en": "Models Prompts and Adapters",
      "aliases": [],
      "kind": "domain",
      "parentId": null,
      "order": 30,
      "summary": "用明确输入、能力合同和发布边界管理模型变化。",
      "question": "怎样把模型、Prompt与适配落实为可比较和可验证的工程选择？",
      "body": "选择模型只是起点。企业Agent还需要可解释的消息角色、context选择、工具协议、结构化输出和版本组合。统一接口的价值是保留可替换边界，不能掩盖各供应商能力差异。支持工具或JSON，也不证明模型能正确完成具体业务。\n\n本分支从Prompt与context进入模型接口，再讨论路由、故障切换、预算和升级。观察基线为2026-10-15；公开模型目录用于发现候选，采用依据仍是自己的任务、权限和外部结果。静态配置在发布时固定，数据generation和授权在每次运行中记录并重新核验。\n\n保留供应商扩展，但让业务工具、Task和证据schema独立。这样才能比较闭源API与微调开放模型，也能在升级时分清模型、harness和资料变化各自的影响。\n\n[OpenAI Agents SDK：模型与provider](https://developers.openai.com/api/docs/guides/agents/models)；[Pydantic AI：Harness能力边界](https://pydantic.dev/docs/ai/harness/)。",
      "blueprint": {
        "inputs": [
          "任务风险与输出合同",
          "模型和Provider候选",
          "规则、证据及工具"
        ],
        "steps": [
          "组装可信输入",
          "验证协议和能力",
          "选择模型与预算",
          "交叉评测后发布"
        ],
        "outputs": [
          "模型适配合同",
          "可追溯版本组合",
          "可靠升级与降级"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/agents/models",
          "label": "OpenAI Agents SDK：模型与provider",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://pydantic.dev/docs/ai/harness/",
          "label": "Pydantic AI：Harness能力边界",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": []
    },
    {
      "id": "models-release",
      "title": "路由、预算与升级",
      "en": "Routing Budgets and Releases",
      "aliases": [],
      "kind": "branch",
      "parentId": "models",
      "order": 30,
      "summary": "按任务资格、质量、成本与时限控制模型使用。",
      "question": "怎样把路由、预算与升级落实为可比较和可验证的工程选择？",
      "body": "路由先满足数据与功能资格，再优化成本；failover不能静默跨越供应商边界。升级使用模型与harness交叉矩阵，运行清单保存实际依赖和数据版本。预算既约束推理，也约束工具、子Agent和验证，达到上限后应提供诚实缺口。\n\n[OpenAI：模型目录](https://developers.openai.com/api/docs/models)；[Codex：异步压缩兼容性源码](https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/async_compaction.rs#L23-L117)。",
      "blueprint": {
        "inputs": [
          "任务分层与候选模型",
          "运行版本和预算"
        ],
        "steps": [
          "筛选资格并路由",
          "核对切换兼容性",
          "运行升级矩阵",
          "灰度与完整回滚"
        ],
        "outputs": [
          "发布决定",
          "费用质量对照"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/models",
          "label": "OpenAI：模型目录",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/async_compaction.rs#L23-L117",
          "label": "Codex：异步压缩兼容性源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": []
    },
    {
      "id": "opencode",
      "title": "OpenCode",
      "en": "OpenCode",
      "aliases": [
        "Anomaly OpenCode",
        "sst/opencode"
      ],
      "kind": "product",
      "parentId": "products-harness",
      "order": 30,
      "summary": "以客户端与HTTP server分离方式提供多provider代码Agent。",
      "question": "它怎样运行Agent，哪些状态和权限仍由应用负责？",
      "body": "观察时点：2026-10-15。以客户端与HTTP server分离方式提供多provider代码Agent。\n\n## 已公开的技术路线与控制边界\n\nTUI/客户端＋OpenAPI server＋工具runtime；研发源码有session_v2、inbox与显式step结果。server工具执行权限与企业SSO/租户网关不同；Basic Auth不能替代完整企业授权。\n\nOpenCode采用客户端与server分离的产品架构。官方文档说明headless server通过HTTP和OpenAPI提供接口，TUI及其他客户端连接它。这使代码Agent可以被程序调用，但server入口本身不等于企业SSO、租户和任务治理；文档中的Basic Auth需要结合外层网络与身份控制评估。\n\n本页引用的固定dev源码属于新的packages/core结构。session_v2保存project、workspace、parent、fork边界、directory、model、permission、token/cache计数与恢复字段；消息、pending和inbox分表并维护顺序。这些设计说明会话不只是聊天文本，也显示本地产品状态与多实例云平台之间仍有差距。\n\nStep runtime对Completed、Retry、Continue、RecoverFull、Compacted和OutputLimit等结果作显式区分。模型流和工具可以并行，中断工作时仍保护最终事件发布；完整重试取决于是否已产生输出。企业可以借鉴这种取消与结果持久化分离，避免外部动作发生后内部只剩一个aborted状态。\n\nCompaction实现保留近期原文并总结更早历史，区分provider原生context。源码仍有演进中尚待完善的细节，也提示多模型行为不能想当然。模型可替换是产品方向，native工具、缓存和opaque压缩仍需逐项验证。\n\n版本与名称要特别小心：原sst/opencode当前迁移到anomalyco/opencode；opencode-ai/opencode是另一个已归档的Go项目，后继为Crush；ducan-ne/OpenCoder又是独立项目。本页的dev SHA也不能当成stable v1.19.1二进制已经具备相同结构。PoC必须锁渠道、包版本和源码。\n\nMIT许可有利于复用，推荐先作为受限代码文件worker集成，而非整仓重写企业认证、数据库和工作流。测试路径迁移、日志增长、重启恢复、取消、provider切换和产物读回；相关issue只是特定环境的测试线索，不能被概括成所有当前版本的缺陷。\n\n适合的集成切片是一个云端受限工作区：应用把Task映射为独立工作目录或环境，经受控HTTP入口提交，读取事件和最终产物。先验证目录与项目身份的迁移、会话恢复和多客户端行为，再考虑增加更多用户。SQLite的本地便捷性不等于可把文件放共享卷供多实例任意写；若改为企业持久层，必须估算核心模型、迁移和上游同步成本。还要验证工具快照如何增长、何时清理以及删除是否保留必要产物。只有这些关键差异可在清晰边界外实现时，集成才比大规模fork更有优势。\n\n## 数据、记忆与模型替换\n\n源码可见SQLite session、消息顺序、fork、token/cache计数与compaction；不能直接当多租户云数据库架构。\n\n多provider是产品方向；每模型原生能力与压缩状态需独立核验。\n\n## 执行、部署与采用取舍\n\nServer在所选环境执行工具，客户端经HTTP/OpenAPI连接。模型驱动循环，显式step结果、会话队列与context压缩。本地或受控云worker；企业入口另加身份、scope和网络边界。\n\n开放源码与client/server边界便于集成，适合代码执行worker。\n\n观察于2026-10-15：latest non-prerelease与研发渠道区分展示；v1.19.1；dev SHA f40dc433cb52eeb3ff5ec7a755f0ba0162216a51\n\n许可边界：MIT。采用前按实际使用方式核验组件、云服务与模型条款。\n\n## 证据范围与未知\n\n固定dev源码已读schema、step和compaction；旧sst入口迁移至anomalyco；另一个opencode-ai项目已归档。\n\n未公开或仍需目标环境验证的部分：stable包与dev结构差异；多实例云持久化；特定provider质量。本页不以产品表面行为推断其隐藏实现。\n\n[OpenCode：HTTP与OpenAPI server](https://opencode.ai/docs/server/)；[OpenCode：session_v2与消息表源码](https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/sql.ts#L22-L144)；[OpenCode：流、工具和取消源码](https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/runner/step.ts#L32-L245)；[OpenCode：摘要与近期原文](https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/compaction.ts#L705-L743)；[OpenCode：MIT许可](https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/LICENSE)。",
      "blueprint": {
        "inputs": [
          "代码或文件Task",
          "OpenCode server与provider",
          "外层企业权限和产物合同"
        ],
        "steps": [
          "锁定发行渠道与版本",
          "通过受控server接口运行",
          "保存消息及工具结果",
          "导出并验证业务产物"
        ],
        "outputs": [
          "代码与文件变更",
          "会话和Step记录",
          "适配及恢复验证"
        ]
      },
      "citations": [
        {
          "url": "https://opencode.ai/docs/server/",
          "label": "OpenCode：HTTP与OpenAPI server",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/sql.ts#L22-L144",
          "label": "OpenCode：session_v2与消息表源码",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/runner/step.ts#L32-L245",
          "label": "OpenCode：流、工具和取消源码",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/compaction.ts#L705-L743",
          "label": "OpenCode：摘要与近期原文",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/LICENSE",
          "label": "OpenCode：MIT许可",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": [
        {
          "target": "agent-session",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent Session的具体产品路线。"
        },
        {
          "target": "agent-cancellation",
          "type": "implements",
          "reason": "公开能力或可见源码体现取消语义的具体产品路线。"
        },
        {
          "target": "context-compaction",
          "type": "implements",
          "reason": "公开能力或可见源码体现上下文压缩的具体产品路线。"
        },
        {
          "target": "model-adapter",
          "type": "complements",
          "reason": "用模型适配层检查采用时的控制边界；不推断未公开内部机制。"
        },
        {
          "target": "event-log",
          "type": "implements",
          "reason": "公开能力或可见源码体现事件日志的具体产品路线。"
        }
      ],
      "productRoute": {
        "vendor": "Anomaly",
        "category": "多Provider代码Harness",
        "execution": "Server在所选环境执行工具，客户端经HTTP/OpenAPI连接。",
        "orchestration": "模型驱动循环，显式step结果、会话队列与context压缩。",
        "context": "会话消息、inbox与近期原文/摘要分开；provider原生context另有兼容边界。",
        "persistence": "源码可见SQLite session、消息顺序、fork、token/cache计数与compaction；不能直接当多租户云数据库架构。",
        "modelBoundary": "多provider是产品方向；每模型原生能力与压缩状态需独立核验。",
        "deployment": "本地或受控云worker；企业入口另加身份、scope和网络边界。",
        "license": "MIT",
        "availability": "观察于2026-10-15：latest non-prerelease与研发渠道区分展示；v1.19.1；dev SHA f40dc433cb52eeb3ff5ec7a755f0ba0162216a51",
        "strengths": "开放源码与client/server边界便于集成，适合代码执行worker。",
        "limits": "待验证或未公开：stable包与dev结构差异；多实例云持久化；特定provider质量。公开能力不等同企业负载与领域任务实测。"
      }
    },
    {
      "id": "products-platforms",
      "title": "托管运行与应用平台",
      "en": "Managed Runtimes and Platforms",
      "aliases": [],
      "kind": "branch",
      "parentId": "products",
      "order": 30,
      "summary": "比较平台承担的运维工作和应用仍需保有的控制。",
      "question": "怎样按技术路线和控制边界比较托管运行与应用平台？",
      "body": "托管harness减少部分环境与循环维护，完整应用平台减少界面和配置工作，二者范围并不相同。对企业最关键的是业务状态、工具身份、数据保留、导出和最终验收由谁负责。API可访问也不等于实际账号具备全部能力，Preview和Beta需单独标注。\n\n[OpenAI：Agent运行时选择](https://developers.openai.com/api/docs/guides/agents)；[Claude Managed Agents：概览](https://platform.claude.com/docs/en/managed-agents/overview)；[Dify：附加许可条件](https://github.com/langgenius/dify/blob/310ce87f9d78313966e5d17753ad36b9725b280b/LICENSE)。",
      "blueprint": {
        "inputs": [
          "云端部署目标",
          "业务权限及数据合同"
        ],
        "steps": [
          "映射平台与应用责任",
          "验证账号及生命周期",
          "测试导出与恢复",
          "核算总成本"
        ],
        "outputs": [
          "平台责任边界",
          "采购与退出验证"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/agents",
          "label": "OpenAI：Agent运行时选择",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://platform.claude.com/docs/en/managed-agents/overview",
          "label": "Claude Managed Agents：概览",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/langgenius/dify/blob/310ce87f9d78313966e5d17753ad36b9725b280b/LICENSE",
          "label": "Dify：附加许可条件",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": []
    },
    {
      "id": "rate-limit-backpressure",
      "title": "限流、背压与公平调度",
      "en": "Rate Limits and Backpressure",
      "aliases": [
        "并发治理",
        "公平排队",
        "背压"
      ],
      "kind": "concept",
      "parentId": "performance-delivery",
      "order": 30,
      "summary": "约束并发进入速度，防止需求超过服务配额和资源。",
      "question": "怎样设计限流、背压与公平调度，并验证其对任务质量与可靠性的影响？",
      "body": "约束并发进入速度，防止需求超过服务配额和资源。\n\n限流约束进入系统的工作速度，背压让上游知道当前容量不足。它们不只是防止服务报错，也决定公平性和尾延迟。模型配额、数据库连接、检索吞吐、sandbox与外部工具各有容量，最慢约束会影响整体完成率。\n\n按租户、用户与任务类型分配并发，交互任务和批量ingest使用不同队列或配额，避免后台吞吐抢占在线资源。热点客户可以有明确预算，但不能无限压住其他工作。队列需要长度、等待时间、取消和过期规则，不能把所有请求无界积压当作可靠接收。\n\n429时遵循服务端提示与带jitter的退避，同时受总deadline约束。多个worker同步重试会形成惊群；简单扩容只会更快撞到供应商配额。应用应控制总并发与请求速率，并区分token速率、请求速率和工具资源，而非只数进程。\n\n调度还需要考虑工作大小。长context和多Agent任务可能占用更多token与连接，不能与短查询完全按请求数等价。可用预计资源作初步分类，实际用量再校准；估计错误要有保护上限，避免一个模型自由发散消耗整个租户额度。\n\n背压应反馈到产品：显示排队、预计范围或可选择的异步执行，而不是一直转圈。到达容量上限时可以拒绝低优先级批任务、降低允许并行或等待，不必静默转到未经批准模型。接受任务也要说明是否已进入可恢复队列。\n\n负载实验同时观察突发、持续高量、单租户热点和供应商降额。报告排队时间、完成时间、公平性、拒绝率、重试放大与有效结果成本。吞吐提高却让大多数用户更慢，不是成功优化；容量决策必须与业务SLO一起看。\n\n**实践重点**：按租户公平排队；交互与批任务隔离；遵循429提示与全局配额。\n\n**验证抓手**：测突发、热点租户和批处理下的尾延迟与公平性。\n\n**常见误区**：无限扩worker放大429风暴和费用。\n\n[OpenAI：Latency optimization](https://developers.openai.com/api/docs/guides/latency-optimization)；[OpenAI：Agent运行时选择](https://developers.openai.com/api/docs/guides/agents)。",
      "blueprint": {
        "inputs": [
          "各层容量和配额",
          "租户优先级与任务大小",
          "队列及deadline"
        ],
        "steps": [
          "按资源和租户限并发",
          "隔离交互与批任务",
          "对超额流量背压",
          "控制退避和恢复节奏"
        ],
        "outputs": [
          "公平任务分配",
          "可观测队列",
          "受控配额和尾延迟"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/latency-optimization",
          "label": "OpenAI：Latency optimization",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://developers.openai.com/api/docs/guides/agents",
          "label": "OpenAI：Agent运行时选择",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "task-scheduler",
          "type": "requires",
          "reason": "本节点的设计需要先明确任务调度。"
        },
        {
          "target": "retry-policy",
          "type": "requires",
          "reason": "本节点的设计需要先明确错误分类与重试。"
        }
      ]
    },
    {
      "id": "retrieval-representation",
      "title": "文档与向量表示",
      "aliases": [],
      "kind": "branch",
      "parentId": "retrieval",
      "order": 30,
      "summary": "表示层决定一段资料用什么边界与背景进入索引。",
      "question": "文档如何变成可检索表示？",
      "body": "表示层决定一段资料用什么边界与背景进入索引。结构切块保留语义单元，父子段提供不同读取粒度，上下文增强补上片段的文档身份。\n\n两者都要保留原文和派生版本。更长片段可能增加理解范围，也可能稀释召回；生成背景可能补充定位，也可能把推断带进索引。按文档类型做消融比复制一个固定chunk大小更可靠。",
      "blueprint": {
        "inputs": [
          "任务问题与可用资料"
        ],
        "steps": [
          "表示层决定一段资料用什么边界与背景进入索引",
          "沿子节点选择合适机制"
        ],
        "outputs": [
          "可验证的检索设计选择"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/contextual-retrieval",
          "label": "官方机制与实现参考",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "runtime-delegation",
      "title": "委派与结果合并",
      "en": "Delegation and Merge",
      "aliases": [],
      "kind": "branch",
      "parentId": "runtime",
      "order": 30,
      "summary": "把可独立验收的工作交给子Agent，并保留合并责任。",
      "question": "怎样从委派与结果合并进入可实施的设计与验证？",
      "body": "多Agent的收益来自真正可并行的工作，而非角色数量。每个分支需要小范围输入、权限子集、预算、产物和验收；父级负责检查证据、去重同源材料与处理冲突。强共享状态的连续编辑应明确owner和版本，不能依赖聊天协商代替并发控制。\n\n[Claude Agent SDK：概览](https://code.claude.com/docs/en/agent-sdk/overview)；[LangGraph：Runner提交源码](https://github.com/langchain-ai/langgraph/blob/889a5ff16f8325113093d517dffd5471a943c760/libs/langgraph/langgraph/pregel/_runner.py#L575-L615)。",
      "blueprint": {
        "inputs": [
          "可分解工作",
          "分支权限与预算"
        ],
        "steps": [
          "定义子合同",
          "并行取证或计算",
          "复核并合并"
        ],
        "outputs": [
          "结构化子产物",
          "冲突与覆盖边界"
        ]
      },
      "citations": [
        {
          "url": "https://code.claude.com/docs/en/agent-sdk/overview",
          "label": "Claude Agent SDK：概览",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://github.com/langchain-ai/langgraph/blob/889a5ff16f8325113093d517dffd5471a943c760/libs/langgraph/langgraph/pregel/_runner.py#L575-L615",
          "label": "LangGraph：Runner提交源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        }
      ],
      "links": []
    },
    {
      "id": "storage-engines",
      "title": "引擎与实现路线",
      "aliases": [],
      "kind": "branch",
      "parentId": "storage",
      "order": 30,
      "summary": "引擎比较围绕现有团队能力、事务需求、过滤分布、排序复杂度与伸缩方式。",
      "question": "哪些检索引擎适合当前团队与负载？",
      "body": "引擎比较围绕现有团队能力、事务需求、过滤分布、排序复杂度与伸缩方式。PostgreSQL共库、独立向量服务、全文搜索引擎和多阶段排序系统各有不同维护边界。\n\n产品页解释实现差异与验证重点，不以厂商排行榜作统一结论。云托管可以降低运维负担，但导出、版本、许可和恢复资格仍应逐项核查。",
      "blueprint": {
        "inputs": [
          "数据与运行要求"
        ],
        "steps": [
          "明确该层职责与约束",
          "按子节点比较并验证"
        ],
        "outputs": [
          "可追溯的数据层决定"
        ]
      },
      "citations": [
        {
          "url": "https://docs.vespa.ai/en/ranking/phased-ranking.html",
          "label": "官方机制与实现参考",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "tool-authorization",
      "title": "工具授权网关",
      "en": "Tool Authorization Gateway",
      "aliases": [
        "权限网关",
        "能力安全"
      ],
      "kind": "concept",
      "parentId": "runtime-tools",
      "order": 30,
      "summary": "在真实执行点核验主体、action、resource和批准范围。",
      "question": "模型提出动作后，谁在真实执行点核验权限？",
      "body": "在真实执行点核验主体、action、resource和批准范围。\n\n模型可以提出行动，只有执行系统能授予真实权限。工具网关应从服务器验证的登录凭证和组织目录获得主体，再检查action、resource、scope及批准状态。prompt中的身份、工具参数中的tenant_id、其他Agent声称的“已获同意”都不能成为授权事实。\n\n权限至少影响模型可见能力、执行API和数据层读取。先缩小工具与知识范围，执行时再次核验，数据库仍限制越权。凭证由网关或vault代持，向模型返回最小必要结果。代码执行与MCP调用经过同一边界，不能因为换了一条技术路径就获得额外权限。\n\n审批只对具体参数和资源版本有效。高风险commit前重新检查当前授权、租约与业务状态；权限撤回还应处理已有context、在途子Agent和待发布产物。缓存命中不免除鉴权。对子Agent委派采用权限子集，避免父级通用凭证被复制到多个不受控执行环境。\n\nMCP安全建议特别涉及OAuth audience、scope、token透传和confused deputy。协议标准化不证明远端server可信；工具定义变化也应触发审查。测试包括跨租户资源、过期批准、旧worker提交、server伪装以及输出中诱导扩权。网关拒绝后loop应停止该动作或请求合法授权，而非改prompt、换工具或再启动子Agent绕过。\n\n网关审计应保存请求来源、动作范围、策略版本和最终决定，但不要把凭证写入trace。对于一条模型生成SQL，即使表名合法，也可能查询超出当前matter或班级的数据；资源过滤必须作用于实际查询。产品可先暴露受限领域接口，以缩小模型需要掌握的权限表面。\n\n拒绝结果要有面向模型的安全原因码和面向审计的详细记录。前者帮助正确停止，后者供授权人员诊断；无需向模型暴露组织目录和凭证细节。\n\n**实践重点**：身份和租户由服务端注入；凭证代持；模型只能请求允许范围。\n\n**验证抓手**：测试跨租户、审批重放、scope缩减与凭证不可见。\n\n**常见误区**：信任prompt自报tenant，或以子Agent/代码绕过网关。\n\n[MCP：安全建议](https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices)；[Claude Code：权限配置](https://code.claude.com/docs/en/permissions)。",
      "blueprint": {
        "inputs": [
          "服务端主体与角色",
          "工具动作和资源",
          "批准、租约及当前策略"
        ],
        "steps": [
          "校验身份与scope",
          "检查资源和参数版本",
          "在提交点重验授权",
          "记录决定并最小化返回"
        ],
        "outputs": [
          "授权或拒绝决定",
          "受控工具执行",
          "可审计访问轨迹"
        ]
      },
      "citations": [
        {
          "url": "https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices",
          "label": "MCP：安全建议",
          "kind": "standard",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://code.claude.com/docs/en/permissions",
          "label": "Claude Code：权限配置",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": [
        {
          "target": "tool-contract",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具接口合同。"
        }
      ]
    },
    {
      "id": "tool-call-correlation",
      "title": "工具调用ID配对",
      "en": "Tool Call Correlation",
      "aliases": [
        "Call ID",
        "工具结果配对"
      ],
      "kind": "concept",
      "parentId": "models-contracts",
      "order": 30,
      "summary": "用稳定call ID关联模型请求、工具执行与结果。",
      "question": "怎样设计工具调用ID配对，并验证其对任务质量与可靠性的影响？",
      "body": "用稳定call ID关联模型请求、工具执行与结果。\n\n模型工具调用ID用于把一次行动请求与执行结果准确关联。一个模型step可以提出多个工具；结果也可能乱序返回或在恢复后补写。缺少稳定身份时，系统可能把公司的财报结果塞给另一个调用，或重复执行已经成功的操作。\n\nOpenAI Agents SDK固定Model接口明确要求每个调用具有非空ID，并在Run及序列化恢复链中保持稳定；变化后的工具身份或payload不能复用旧ID。输出要保留原call ID，以便runtime识别已完成重放。这是可见接口约束，不代表它自动替应用完成业务幂等。\n\n应分别保存model_call_id、tool_call_id、business_operation_id与attempt_id。前两个用于模型轨迹关联，业务ID表示同一被授权动作，attempt表示网络尝试。只读调用可一对一映射，复杂批量写入则可能需要子操作清单，不能把整个脚本都压成一个不可解释的ID。\n\n流式参数先按调用身份累积，完整解析并校验后再执行。模型若返回重复ID、缺失ID或同ID不同参数，应明确报协议错误，不擅自合并。供应商原生执行的工具与应用执行的工具也需标清责任，避免看到tool-call事件就重复本地执行。\n\n恢复时从已提交结果重建配对，缺失结果进入pending或unknown。不能为了满足消息格式而编造一个成功结果；也不能把旧审批绑定到新payload。OpenCode源码对未完成调用补明确错误，提示这种尾部状态应受治理。\n\n测试并行工具乱序、相同名称不同参数、断流中止、序列化恢复和重复回调。验收看每个结果能否准确归属以及外部动作次数是否正确。日志中“都有ID”只是第一步，身份在整个生命周期保持语义一致才是关键。\n\n界面可隐藏底层ID，但审计必须能沿ID找到原始请求、批准和实际回执。否则人工处理异常时容易对错操作。\n\n**实践重点**：ID在run和恢复链内稳定，工具身份或参数改变不能复用旧ID。\n\n**验证抓手**：测并行多工具、重放、截断与恢复时的ID不变量。\n\n**常见误区**：丢失或重复ID导致结果串线和重复执行。\n\n[Agents SDK：Model接口和call ID约束](https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/models/interface.py#L37-L80)；[OpenCode：流、工具和取消源码](https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/runner/step.ts#L32-L245)。",
      "blueprint": {
        "inputs": [
          "模型调用流",
          "完整工具参数",
          "历史工具结果与操作ID"
        ],
        "steps": [
          "按call ID累积参数",
          "校验身份与payload一致",
          "执行并配对结果",
          "恢复时复用已提交结果"
        ],
        "outputs": [
          "无歧义调用链",
          "缺失或冲突错误",
          "可安全重放历史"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/models/interface.py#L37-L80",
          "label": "Agents SDK：Model接口和call ID约束",
          "kind": "code",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/runner/step.ts#L32-L245",
          "label": "OpenCode：流、工具和取消源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "model-adapter",
          "type": "requires",
          "reason": "本节点的设计需要先明确模型适配层。"
        },
        {
          "target": "idempotent-side-effects",
          "type": "requires",
          "reason": "本节点的设计需要先明确业务副作用幂等。"
        }
      ]
    },
    {
      "id": "tool-result-cache",
      "title": "工具结果缓存",
      "en": "Tool Result Cache",
      "aliases": [
        "API结果缓存",
        "计算缓存"
      ],
      "kind": "concept",
      "parentId": "performance-cache",
      "order": 30,
      "summary": "复用符合资源版本和时效约束的读工具结果。",
      "question": "怎样设计工具结果缓存，并验证其对任务质量与可靠性的影响？",
      "body": "复用符合资源版本和时效约束的读工具结果。\n\n工具结果缓存适合有清楚时效和资源版本的读操作。历史财报、当前行情、余额、合同状态和课程资料具有不同变化速度，不能共用一个TTL。缓存减少外部延迟和费用，但也可能把旧状态带入高风险决策。\n\n缓存键应表达工具版本、规范化参数、主体范围、资源版本与数据时间。结果保存生成时间、来源和有效期，让调用方知道能否复用。对于会计数据，还要区分原始披露、追溯修订和读取时点；同一公司同一季度不一定永远只有一个值。\n\n写操作通常不应当成普通读缓存。重复提交同一动作依赖业务幂等和receipt，而非把上次HTTP响应放进缓存就结束。模型请求修改同一记录但参数不同，是新候选动作；不能因为命中旧响应而隐去变化。未知结果也不能缓存成成功。\n\n高风险commit前重新读取业务状态，例如报价是否仍有效、目标记录版本是否匹配、审批是否过期。工具网关执行当前权限检查，cache hit不提供额外授权。凭证scope变化、资源删除和owner变化也应触发失效。\n\n可以把纯计算缓存与外部查询分开。确定性计算的输入包含数据hash、公式和代码版本，适合长期复用；动态业务查询需要更短窗口和read-back。保存可复算产物，便于判断缓存结果来自哪个口径，而不是只看到一个数字。\n\n测试TTL边界、资源更新、权限撤回、并发读写和提交前版本变化。优化收益看外部请求减少、完成时间和验收质量；陈旧结果导致的人工返工也计入成本。缓存必须有明确owner和失效接口，否则会成为难以诊断的第二份业务数据库。\n\n**实践重点**：按资源、参数、数据版本与TTL区分行情、历史报表、余额等。\n\n**验证抓手**：检验版本变化、TTL过期和提交前重新读。\n\n**常见误区**：高风险提交前使用陈旧状态，或缓存有副作用操作。\n\n[Temporal：执行状态与外部副作用](https://docs.temporal.io/ai/featured/memory-state-stripe)；[OpenAI：Latency optimization](https://developers.openai.com/api/docs/guides/latency-optimization)。",
      "blueprint": {
        "inputs": [
          "工具参数和版本",
          "资源及数据时间",
          "当前权限与TTL策略"
        ],
        "steps": [
          "区分纯计算与动态查询",
          "构造版本化缓存键",
          "命中后复核权限",
          "提交前重新读状态"
        ],
        "outputs": [
          "可追溯读结果",
          "明确有效期",
          "陈旧与节省指标"
        ]
      },
      "citations": [
        {
          "url": "https://docs.temporal.io/ai/featured/memory-state-stripe",
          "label": "Temporal：执行状态与外部副作用",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://developers.openai.com/api/docs/guides/latency-optimization",
          "label": "OpenAI：Latency optimization",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "tool-contract",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具接口合同。"
        },
        {
          "target": "cache-invalidation",
          "type": "requires",
          "reason": "本节点的设计需要先明确缓存依赖失效。"
        }
      ]
    },
    {
      "id": "deepseek-harness",
      "title": "DeepSeek Harness",
      "en": "DeepSeek Harness",
      "aliases": [
        "dsh",
        "DeepSeek Harness"
      ],
      "kind": "product",
      "parentId": "products-harness",
      "order": 40,
      "summary": "以Cordis插件体系构建的开源Agent harness。",
      "question": "它怎样运行Agent，哪些状态和权限仍由应用负责？",
      "body": "观察时点：2026-10-15。以Cordis插件体系构建的开源Agent harness。\n\n## 已公开的技术路线与控制边界\n\n插件组合＋事件日志衍生context；turn和step边界消费队列输入。插件与生命周期作用域控制能力；采用前需验证接口变化与持久化。\n\nDeepSeek Harness是当前公开的插件型harness候选，官方README把它描述为由Cordis支撑、能力通过插件组合的系统。它适合研究执行外围怎样拆分，不应因为大模型厂商发布就直接假设已经达到企业长期兼容与稳定运维要求。观察时点的README明确标developer preview，并提示可能出现破坏兼容的变化。\n\n固定agent-loop源码显示每次请求从session日志派生，驱动器有idle、maintenance与running阶段；inbox区分followup到next-turn和steer到next-step。这个边界对持续交互有直接意义：补充方向与新任务不应总是混在一个队列中，取消之后到达的新输入也需要清楚归类。\n\n事件日志与projection让上下文成为可生成视图，而非可随意覆盖的一份文本。企业可借鉴日志、运行态与客户端展示分离，保留原始事件及版本，并限制谁能写入。公开repo中还有session持久化和格式演进等模块，但阅读文件存在不等于已经验证所有恢复与迁移路径。\n\n全插件方案的优势是能力边界可组合，代价是插件兼容、生命周期、作用域与默认配置需要更严格治理。一个插件能注册工具，并不代表它能持有所有企业凭证；插件升级也可能改变模型输入和行为。企业应审查许可、依赖与权限，而不是无条件加载生态中的全部扩展。\n\n社区中存在个人定制下游，采用时应追溯到官方仓库并区分默认与扩展能力。个人定制的搜索provider和规则不能当成官方默认能力，也不应把作者私人经验直接移入公司memory。采用前固定官方基准SHA和自己添加的补丁，保持来源与升级路径清楚。\n\n建议将它列为技术观察或隔离PoC对象，使用非敏感测试资料验证turn/step输入、取消、session恢复、模型adapter和插件卸载。若主业务需要稳定发布合同，可先使用证据更成熟且已经通过代表任务验证的runtime。MIT文件说明公开代码许可，不能抵消preview阶段的迁移与维护成本。\n\n隔离PoC可从一个只读资料任务开始，只启用必要模型adapter和检索插件，保存输入队列、事件及产物。分别测试运行中steer、下一turn新任务、取消后新输入与插件卸载，检查状态是否一致。随后才验证持久session和格式升级，保留旧日志是否还能恢复的证据。插件越灵活，越要避免配置、权限与默认行为散落到难以追踪的位置。正式采用的门槛应包括稳定版本、核心流程、代表性改造及恢复实测；其中任何未知都不能用开源许可或厂商声誉补分。\n\n## 数据、记忆与模型替换\n\n固定源码可见session日志、projection、inbox、followup与steer语义。\n\n不能因插件化就推断任意provider等价支持；以具体adapter核验。\n\n## 执行、部署与采用取舍\n\n在选择的Node.js及支持环境执行，能力由插件组合。Cordis插件体系，默认loop基于session日志及turn/step inbox。隔离本地或云PoC；正式部署前锁定版本与兼容合同。\n\n模块与事件边界公开，适合研究插件化harness和持续交互。\n\n观察于2026-10-15：Developer preview；本次未发现latest public release；SHA 86a402200d95fecef4529d969836f1fe13c6cb0d\n\n许可边界：MIT。采用前按实际使用方式核验组件、云服务与模型条款。\n\n## 证据范围与未知\n\n已读官方README、loop源码和MIT；官方明确developer preview及破坏性兼容变化。\n\n未公开或仍需目标环境验证的部分：稳定发布约束；多模型适配覆盖；企业级恢复和性能。本页不以产品表面行为推断其隐藏实现。\n\n[DeepSeek Harness：固定源码](https://github.com/deepseek-ai/deepseek-harness/tree/86a402200d95fecef4529d969836f1fe13c6cb0d)；[DeepSeek Harness：事件日志驱动循环](https://github.com/deepseek-ai/deepseek-harness/blob/86a402200d95fecef4529d969836f1fe13c6cb0d/packages/core/agent-loop/src/agent.ts#L42-L168)；[DeepSeek Harness：MIT许可](https://github.com/deepseek-ai/deepseek-harness/blob/86a402200d95fecef4529d969836f1fe13c6cb0d/LICENSE)。",
      "blueprint": {
        "inputs": [
          "官方固定版本与插件集",
          "测试Task和模型adapter",
          "Session及权限合同"
        ],
        "steps": [
          "审阅插件和生命周期",
          "验证turn/step输入",
          "测试取消及持久恢复",
          "比较兼容与维护成本"
        ],
        "outputs": [
          "插件化执行体验",
          "事件与恢复证据",
          "Preview采用边界"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/deepseek-ai/deepseek-harness/tree/86a402200d95fecef4529d969836f1fe13c6cb0d",
          "label": "DeepSeek Harness：固定源码",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/deepseek-ai/deepseek-harness/blob/86a402200d95fecef4529d969836f1fe13c6cb0d/packages/core/agent-loop/src/agent.ts#L42-L168",
          "label": "DeepSeek Harness：事件日志驱动循环",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/deepseek-ai/deepseek-harness/blob/86a402200d95fecef4529d969836f1fe13c6cb0d/LICENSE",
          "label": "DeepSeek Harness：MIT许可",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": [
        {
          "target": "agent-harness",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent Harness的具体产品路线。"
        },
        {
          "target": "agent-loop",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent执行循环的具体产品路线。"
        },
        {
          "target": "event-log",
          "type": "implements",
          "reason": "公开能力或可见源码体现事件日志的具体产品路线。"
        },
        {
          "target": "agent-session",
          "type": "implements",
          "reason": "公开能力或可见源码体现Agent Session的具体产品路线。"
        },
        {
          "target": "agent-cancellation",
          "type": "implements",
          "reason": "公开能力或可见源码体现取消语义的具体产品路线。"
        }
      ],
      "productRoute": {
        "vendor": "DeepSeek",
        "category": "插件型开源Harness",
        "execution": "在选择的Node.js及支持环境执行，能力由插件组合。",
        "orchestration": "Cordis插件体系，默认loop基于session日志及turn/step inbox。",
        "context": "公开默认loop从session日志和projection组装下一请求，区分turn与step输入。",
        "persistence": "固定源码可见session日志、projection、inbox、followup与steer语义。",
        "modelBoundary": "不能因插件化就推断任意provider等价支持；以具体adapter核验。",
        "deployment": "隔离本地或云PoC；正式部署前锁定版本与兼容合同。",
        "license": "MIT",
        "availability": "观察于2026-10-15：Developer preview；本次未发现latest public release；SHA 86a402200d95fecef4529d969836f1fe13c6cb0d",
        "strengths": "模块与事件边界公开，适合研究插件化harness和持续交互。",
        "limits": "待验证或未公开：稳定发布约束；多模型适配覆盖；企业级恢复和性能。公开能力不等同企业负载与领域任务实测。"
      }
    },
    {
      "id": "effective-result-cost",
      "title": "有效结果成本",
      "en": "Cost per Verified Outcome",
      "aliases": [
        "有效任务成本",
        "TCO"
      ],
      "kind": "concept",
      "parentId": "performance-delivery",
      "order": 40,
      "summary": "把系统费用与人工复核返工成本除以通过验收的任务数。",
      "question": "怎样设计有效结果成本，并验证其对任务质量与可靠性的影响？",
      "body": "把系统费用与人工复核返工成本除以通过验收的任务数。\n\n每百万token单价只能描述模型计费的一部分，不能代表Agent完成工作的真实成本。有效结果成本应把系统费用和人工复核返工成本合计，再除以通过验收的任务数。失败、重试、judge和子Agent都属于为获得结果付出的成本，不能被排除后展示便宜。\n\n一次Run的费用可分模型普通输入、缓存读、缓存写、输出、工具与搜索、数据许可、计算、存储和网络。按供应商账单互斥分类，避免将cache_write同时计入普通输入；不同模型的usage字段与价格合同可能不同，要通过adapter保留原始分类并对账。\n\n人工时间往往决定商业价值。便宜模型可能多生成错误表格、需要专家补证或返工；高档模型若减少这些工作，整体更经济。反过来，高档模型用于简单分类未必划算。比较应在相同任务范围、质量门槛和外部数据许可下进行，而非拿一个简化demo与完整生产系统比。\n\n成本还包括框架接入、权限与加固、评测、数据迁移、日常运维、升级回归和退出。托管harness减少部分基础设施人力，可能增加供应商状态耦合；整仓fork看似启动快，却要持续承担上游同步和兼容。工时与现金分列，对未知项给范围，不虚构精确人日。\n\n业务指标不能全部压成美元。金融投资结果受市场与风险暴露影响，教育学习增益需后续观察，法律错误可能有长尾后果。费用报告同时显示严重错误、覆盖、人工分钟和用户完成率，而不是用一个总分掩盖高风险失败。\n\n使用代表性负载的trace、账单与人工记录估算，并做预算敏感性分析。若验收标准改变，分母也改变，应保留版本。优化的目标是以可接受风险得到更多有效结果，而不是让单次调用看起来更省。\n\n**实践重点**：计算模型、缓存、工具、数据许可、沙箱、judge、子Agent和人类分钟。\n\n**验证抓手**：使用trace与账单对账，并同时报告质量和严重错误。\n\n**常见误区**：只比较每百万token单价，忽略失败和返工。\n\n[OpenAI：Prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching)；[OpenAI：模型目录](https://developers.openai.com/api/docs/models)。",
      "blueprint": {
        "inputs": [
          "Run用量及账单",
          "验收通过任务数",
          "人工复核和维护成本"
        ],
        "steps": [
          "按互斥类别核算费用",
          "计入失败和返工",
          "按质量门槛计算分母",
          "比较同范围总成本"
        ],
        "outputs": [
          "有效结果成本",
          "人工与严重错误指标",
          "采用及预算判断"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/prompt-caching",
          "label": "OpenAI：Prompt caching",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://developers.openai.com/api/docs/models",
          "label": "OpenAI：模型目录",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "completion-contract",
          "type": "requires",
          "reason": "本节点的设计需要先明确任务完成合同。"
        },
        {
          "target": "execution-run",
          "type": "requires",
          "reason": "本节点的设计需要先明确执行Run。"
        }
      ]
    },
    {
      "id": "execution-run",
      "title": "执行Run",
      "en": "Execution Run",
      "aliases": [
        "执行尝试",
        "Run实例"
      ],
      "kind": "concept",
      "parentId": "runtime-task-session",
      "order": 40,
      "summary": "某项Task在指定发布版本和预算下的一次执行尝试。",
      "question": "重试、恢复和新执行尝试应该怎样区分？",
      "body": "某项Task在指定发布版本和预算下的一次执行尝试。\n\nRun是Task的一次执行尝试。它绑定部署版本、开始条件、预算、worker租约和checkpoint；其中可以有多个Turn、Step和ModelCall。网络重试通常不是新Run，恢复同一次执行也不必重新定义业务动作。清楚区分这些对象，才容易分析成本、失败原因和发布回归。\n\n例如某次合同研究因模型服务故障暂停，worker重启后可以从同一Run继续；若业务owner修改了合同版本和验收，则应记录新条件并决定创建新Run。两种情况都不能简单把随机Run ID当外部幂等键。相同被授权动作在恢复链中要保持操作身份，新的合法动作才建立新ID。\n\nRun快照应包含模型与harness版本、prompt渲染引用、工具schema、来源generation、时间边界、路由理由及费用。动态ACL不能被冻结成永久授权；恢复时重新核验。事件将每个Attempt和外部回执挂到Run下，避免模型调用结束后丢掉仍在执行的工具状态。\n\n测试需要在不同边界终止worker：模型返回后、工具提交前、外部成功但回执未存时，以及验证通过前。目标是恢复时知道哪些结果可复用、哪些动作需要对账，而非重新自由生成关键决定。比较模型实验也以Run为单位保留输入、预算和结果，避免把多次尝试中的最好答案当一次执行的可靠性。\n\n同一个Task的不同Run应可比较：输入条件是否相同，是否使用相同来源窗口，人工是否介入，哪一步触发重试。没有这些信息，失败后再跑一次得到好结果，可能只是数据更新或人为修订所致。运行比较应保留这些差异，而不是只统计最终成功的那一次。\n\n可复现记录不要求公开模型私有思维链。保留输入引用、决策摘要、行动与外部证据即可支持业务审查。对供应商不可固定的行为，应如实标为复现限制，而非承诺完全相同输出。\n\n**实践重点**：记录attempt、租约、模型和checkpoint；恢复不必创建新的业务动作。\n\n**验证抓手**：检验同Task多次Run以及恢复后的副作用去重。\n\n**常见误区**：每次重试生成全新动作身份而重复生效。\n\n[Temporal：执行状态与外部副作用](https://docs.temporal.io/ai/featured/memory-state-stripe)；[LangGraph：Checkpoint模型源码](https://github.com/langchain-ai/langgraph/blob/889a5ff16f8325113093d517dffd5471a943c760/libs/checkpoint/langgraph/checkpoint/base/__init__.py#L93-L123)。",
      "blueprint": {
        "inputs": [
          "Task合同版本",
          "部署和模型快照",
          "预算与执行租约"
        ],
        "steps": [
          "创建执行尝试",
          "关联Step和工具Attempt",
          "持久提交checkpoint",
          "恢复或结束Run"
        ],
        "outputs": [
          "执行轨迹",
          "费用与失败分类",
          "Task候选结果"
        ]
      },
      "citations": [
        {
          "url": "https://docs.temporal.io/ai/featured/memory-state-stripe",
          "label": "Temporal：执行状态与外部副作用",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://github.com/langchain-ai/langgraph/blob/889a5ff16f8325113093d517dffd5471a943c760/libs/checkpoint/langgraph/checkpoint/base/__init__.py#L93-L123",
          "label": "LangGraph：Checkpoint模型源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        }
      ],
      "links": [
        {
          "target": "business-task",
          "type": "requires",
          "reason": "本节点的设计需要先明确业务Task。"
        },
        {
          "target": "agent-definition-version",
          "type": "requires",
          "reason": "本节点的设计需要先明确Agent定义与版本。"
        }
      ]
    },
    {
      "id": "google-adk",
      "title": "Google ADK",
      "en": "Google ADK",
      "aliases": [
        "Agent Development Kit",
        "ADK"
      ],
      "kind": "product",
      "parentId": "products-frameworks",
      "order": 40,
      "summary": "Google生态的Agent和图Workflow开发框架。",
      "question": "它怎样运行Agent，哪些状态和权限仍由应用负责？",
      "body": "观察时点：2026-10-15。Google生态的Agent和图Workflow开发框架。\n\n## 已公开的技术路线与控制边界\n\nAgent与Workflow runtime，支持任务节点、人工交互和云部署入口。应用选择工具和业务状态；框架及云部署服务各自有运行控制边界。\n\nGoogle ADK提供Agent与Workflow开发入口，适合Google生态团队进入候选。当前固定README已经出现图Workflow runtime、任务节点、人工交互和部署方式，不宜只用早期Sequential、Parallel和Loop的印象概括现行框架。\n\nAgent在阶段内理解与选工具，Workflow组合阶段和依赖；企业仍要定义Task合同与验收。公开部署入口包括Cloud Run等方式，云端优先并不要求自己运营模型推理，但应用身份、客户数据范围、工具凭证和审计仍需与所选云服务对接。\n\n本页的证据成熟度主要是官方README、发布元数据和Apache-2.0文件核实，没有声称核心流程已在企业环境跑通。session、state、持久化和记忆能力要按实际后端配置验证，不能从框架名称推断跨会话权限、删除传播和长期学习自动完成。\n\n对金融或法律任务，先把引用、计算与权威状态做成独立工具，再将它们接到框架；教育任务则保留课程和学生scope。这样即使未来替换runtime，领域工具和评测仍可复用。原生Google功能与其他provider支持也分别检查，统一模型接口不能消除schema、tool和context差异。\n\nPoC可与一条非Google主栈方案做同任务对照，固定资料、模型档位、预算和验收。观察开发成本、恢复行为、调用次数、尾延迟与人工修订。没有必要为了完整性同时启用多套工作流，尤其不能让外层队列和内层workflow各自重放同一业务动作。\n\n版本管理应记录ADK包、Google SDK、模型ID、工具定义、工作流和数据generation。部署升级前测试人工等待、worker重启和旧状态读取；权限撤回时处理已进入context的材料。框架拥有部署示例，不等于企业账号具备所有地区能力或服务等级，采购与目标环境契约要单独完成。\n\n例如教育辅导任务可用Agent理解学生当前错误，Workflow安排诊断、提示和迁移题，领域工具负责课程范围与评分。这里模型表达质量、流程合法性和学习保持是三个不同验收面。切换模型后重新测试工具格式、提示策略和拒绝行为；部署到云后再测并发、冷启动和学生scope。对于需要跨天教师批准的正式反馈，恢复时重新鉴权，避免旧班级成员或旧课程版本继续生效。这样能够评估Google生态的实际接入收益，而不是只展示部署命令成功。\n\n## 数据、记忆与模型替换\n\nsession/state与数据服务按所选后端部署；不能从框架存在推断企业长期memory已完成。\n\n有模型与工具扩展方向；原生Google功能与其他provider能力需逐项验证。\n\n## 执行、部署与采用取舍\n\n应用选择执行环境；云部署接口与模型服务分层。当前README描述图Workflow、Agent及任务节点组合。可容器化部署并接Cloud Run等入口；目标账号能力另核。\n\nGoogle Cloud和Gemini主栈团队接入自然，适合评估原生生态协同。\n\n观察于2026-10-15：具体部署与云能力按账号核验；v2.12.0；SHA 203223f5ec74bec86487f91942794a1b0c564131\n\n许可边界：Apache-2.0。采用前按实际使用方式核验组件、云服务与模型条款。\n\n## 证据范围与未知\n\n固定README、发布元数据和Apache-2.0文件已核；未完成核心流程实测。\n\n未公开或仍需目标环境验证的部分：provider覆盖细节；三域memory质量；目标区域部署契约。本页不以产品表面行为推断其隐藏实现。\n\n[Google ADK：固定源码](https://github.com/google/adk-python/tree/203223f5ec74bec86487f91942794a1b0c564131)；[Google ADK：Apache-2.0许可](https://github.com/google/adk-python/blob/203223f5ec74bec86487f91942794a1b0c564131/LICENSE)。",
      "blueprint": {
        "inputs": [
          "领域Agent与Workflow定义",
          "Google及其他工具配置",
          "企业身份和数据scope"
        ],
        "steps": [
          "选择实际部署后端",
          "接入领域工具与模型",
          "运行阶段和局部Agent",
          "验证恢复与结果"
        ],
        "outputs": [
          "图流程和Agent产物",
          "云部署责任图",
          "同任务技术路线比较"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/google/adk-python/tree/203223f5ec74bec86487f91942794a1b0c564131",
          "label": "Google ADK：固定源码",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/google/adk-python/blob/203223f5ec74bec86487f91942794a1b0c564131/LICENSE",
          "label": "Google ADK：Apache-2.0许可",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": [
        {
          "target": "agent-workflow",
          "type": "implements",
          "reason": "公开能力或可见源码体现Workflow与局部Agent的具体产品路线。"
        },
        {
          "target": "model-capability-registry",
          "type": "implements",
          "reason": "公开能力或可见源码体现模型能力注册的具体产品路线。"
        },
        {
          "target": "human-approval",
          "type": "implements",
          "reason": "公开能力或可见源码体现人工审批合同的具体产品路线。"
        },
        {
          "target": "agent-definition-version",
          "type": "complements",
          "reason": "用Agent定义与版本检查采用时的控制边界；不推断未公开内部机制。"
        }
      ],
      "productRoute": {
        "vendor": "Google",
        "category": "Agent与Workflow开发框架",
        "execution": "应用选择执行环境；云部署接口与模型服务分层。",
        "orchestration": "当前README描述图Workflow、Agent及任务节点组合。",
        "context": "Agent与Workflow组合任务上下文；所选模型、工具和持久后端需逐项验证。",
        "persistence": "session/state与数据服务按所选后端部署；不能从框架存在推断企业长期memory已完成。",
        "modelBoundary": "有模型与工具扩展方向；原生Google功能与其他provider能力需逐项验证。",
        "deployment": "可容器化部署并接Cloud Run等入口；目标账号能力另核。",
        "license": "Apache-2.0",
        "availability": "观察于2026-10-15：具体部署与云能力按账号核验；v2.12.0；SHA 203223f5ec74bec86487f91942794a1b0c564131",
        "strengths": "Google Cloud和Gemini主栈团队接入自然，适合评估原生生态协同。",
        "limits": "待验证或未公开：provider覆盖细节；三域memory质量；目标区域部署契约。公开能力不等同企业负载与领域任务实测。"
      }
    },
    {
      "id": "idempotent-side-effects",
      "title": "业务副作用幂等",
      "en": "Idempotent Side Effects",
      "aliases": [
        "幂等操作",
        "去重"
      ],
      "kind": "concept",
      "parentId": "runtime-tools",
      "order": 40,
      "summary": "让同一被授权动作在重试与恢复中只产生预期效果。",
      "question": "怎样让恢复和重试不重复产生同一业务效果？",
      "body": "让同一被授权动作在重试与恢复中只产生预期效果。\n\n幂等针对的是同一个业务动作，而非同一条网络请求。工具可能已经成功创建工单，但响应在途中丢失；如果恢复后重新生成ID再创建，业务就重复发生。稳定操作身份必须先于外部调用保存，并在重试、进程恢复和必要的Run切换中保持。\n\n理想情况是接收端支持幂等键，并检查相同键是否对应相同规范化参数。已完成动作返回原结果；参数改变不能沿用旧键。没有原生支持时，可以利用目标唯一约束或可查询的业务标识实现去重。无法可靠查询或去重的高风险动作，要暂停对账，不能声称客户端保存过一个UUID就已经exactly-once。\n\n幂等键不能过宽。用户明确要求再次发送、创建第二张合法订单或对新资源版本执行操作，需要新业务身份；不能为了防重复而吞掉新的合法工作。批准hash、operation_id和attempt_id分别代表授权内容、业务动作和网络尝试，不宜混用。\n\n持久工作流也可能重跑Activity，外部效果仍由应用合同保证。工具调用ID有助关联，但模型request_id不能直接替代业务身份。验证应在提交前、外部成功后和回执落盘前分别制造故障，再重试与恢复；对照外部记录数量、参数和receipt，而不是只检查本地日志是否去重。\n\n操作参数的规范化规则也应版本化。日期格式、金额精度、收件人集合顺序等差异，可能使同一动作产生不同hash，也可能把实质不同的动作错误合并。应以业务含义定义相等性，并保留原始批准内容；这类规则适合确定性代码与边界测试，不应交给模型临场判断。\n\n幂等记录需要明确保存期限。保留期短于客户端重试或工作流恢复窗口，会在旧任务重放时重新产生效果。\n\n**实践重点**：操作ID先持久化；接收端唯一键或幂等接口；跨Run沿用同动作身份。\n\n**验证抓手**：工具成功后断网再重试，检查是否只生效一次。\n\n**常见误区**：每次网络尝试生成不同ID，或把所有合法动作复用一个ID。\n\n[Temporal：执行状态与外部副作用](https://docs.temporal.io/ai/featured/memory-state-stripe)；[Agents SDK：Model接口和call ID约束](https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/models/interface.py#L37-L80)。",
      "blueprint": {
        "inputs": [
          "被授权业务动作",
          "规范化请求参数",
          "目标系统幂等能力"
        ],
        "steps": [
          "预写稳定operation_id",
          "提交带幂等键请求",
          "重复时读原结果",
          "新合法动作生成新身份"
        ],
        "outputs": [
          "单一预期业务效果",
          "Attempt关联",
          "可复用外部回执"
        ]
      },
      "citations": [
        {
          "url": "https://docs.temporal.io/ai/featured/memory-state-stripe",
          "label": "Temporal：执行状态与外部副作用",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/models/interface.py#L37-L80",
          "label": "Agents SDK：Model接口和call ID约束",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        }
      ],
      "links": [
        {
          "target": "tool-contract",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具接口合同。"
        }
      ]
    },
    {
      "id": "knowledge-domain-contracts",
      "title": "领域资料合同",
      "aliases": [
        "domain data contract"
      ],
      "kind": "branch",
      "parentId": "knowledge",
      "order": 40,
      "summary": "以领域实体、时间、授权和证据字段约束知识使用。",
      "question": "三个专业领域分别要求什么数据合同？",
      "body": "相同的检索框架进入不同领域时，资料资格和正确性口径会改变。金融问题需要知道某条数据何时可得，法律问题需要知道何地何时适用，教育问题则要区分教材事实与对学生状态的估计。\n\n这组页面只定义领域数据的身份、时间、授权和来源字段，避免每个场景重新发明一套知识模型。它们不宣称通用Agent已经具备投资收益、法律效力审查或教学增益；这些结果还需要各自的工具、专家标准和端到端验证。",
      "blueprint": {
        "inputs": [
          "领域问题与资料来源"
        ],
        "steps": [
          "确定实体和时间语义",
          "约束用途与可见范围",
          "建立领域证据字段"
        ],
        "outputs": [
          "金融、法律、教育数据合同"
        ]
      },
      "citations": [
        {
          "url": "https://www.sec.gov/search-filings/edgar-application-programming-interfaces",
          "label": "SEC：财务资料接入",
          "kind": "official-doc"
        },
        {
          "url": "https://wiki.free.law/c/courtlistener/help/api/rest/v4/search",
          "label": "CourtListener：法律检索覆盖",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "memory-governance",
      "title": "准入、更新与撤回",
      "aliases": [],
      "kind": "branch",
      "parentId": "memory",
      "order": 40,
      "summary": "候选写入会把当前输入带到未来任务，因此准入、scope、时间、更正和撤回必须明确。",
      "question": "怎样控制记忆的长期影响？",
      "body": "候选写入会把当前输入带到未来任务，因此准入、scope、时间、更正和撤回必须明确。同步与后台整理又引入并发和一致性，程序性行为的修改应拥有独立发布边界。\n\n本组围绕可观察失败展开：过度记忆、漏记、串scope、旧值覆盖新值、删除后复活，以及第三方输入变成持续指令。每条控制都需要正常案例与对抗案例，不能只靠禁止全部写入获得安全分数。",
      "blueprint": {
        "inputs": [
          "记忆合同和任务需要"
        ],
        "steps": [
          "按子节点选择机制",
          "验证跨Session效果与边界"
        ],
        "outputs": [
          "可维护的记忆设计"
        ]
      },
      "citations": [
        {
          "url": "https://help.getzep.com/v4/memory-security",
          "label": "官方机制与实现参考",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "performance",
      "title": "缓存、延迟与成本",
      "en": "Caching Latency and Cost",
      "aliases": [],
      "kind": "domain",
      "parentId": null,
      "order": 40,
      "summary": "按正确性和权限边界优化整项任务的关键路径。",
      "question": "怎样把缓存、延迟与成本落实为可比较和可验证的工程选择？",
      "body": "性能优化不能只看首个token或每百万token价格。企业任务需要通过验收，实际成本包括失败、工具、验证和人工返工。缓存也分不同层：前缀计算、候选证据、工具结果与最终答案，拥有不同的失效和授权要求。\n\n本分支先解释缓存复用和依赖失效，再讨论关键路径、deadline、背压和有效结果成本。观察基线为2026-10-15；所有SLO需用代表负载验证，厂商演示数字不能作为本项目承诺。先定位重复轮次和长工具输出，再决定是否需要更复杂基础设施。\n\n优化必须保留证据、验收与当前权限。源撤回可能影响已进入context的资料，不能只删除一个缓存键；降低延迟也不应靠省略关键验证。\n\n[OpenAI：Latency optimization](https://developers.openai.com/api/docs/guides/latency-optimization)；[OpenAI：Prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching)。",
      "blueprint": {
        "inputs": [
          "端到端trace与账单",
          "任务SLO与风险",
          "缓存依赖及权限"
        ],
        "steps": [
          "识别关键路径",
          "选择正确缓存层",
          "控制deadline和容量",
          "核对有效结果质量成本"
        ],
        "outputs": [
          "可验证性能收益",
          "陈旧与隔离指标",
          "预算和容量决策"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/latency-optimization",
          "label": "OpenAI：Latency optimization",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://developers.openai.com/api/docs/guides/prompt-caching",
          "label": "OpenAI：Prompt caching",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": []
    },
    {
      "id": "planning-replanning",
      "title": "规划与再规划",
      "en": "Planning and Replanning",
      "aliases": [
        "任务规划",
        "再规划"
      ],
      "kind": "concept",
      "parentId": "runtime-harness",
      "order": 40,
      "summary": "根据目标与新证据选择和修订后续步骤。",
      "question": "怎样让计划帮助完成任务，并在证据改变时正确修订？",
      "body": "根据目标与新证据选择和修订后续步骤。\n\n计划是关于下一步的可修订假设，不是Agent能力的证明。长任务需要把目标拆成可检查的子结果，标明依赖和未知项；但执行中发现新的报表口径、合同版本或学生误解后，计划必须能够改变。独立的planner模型并非必需，主模型也可以维护结构化计划。\n\n先规划后执行在目标明确、步骤可预测时有价值；在资料逐步暴露的研究任务中，过细计划容易提前锁定错误路径。比较三家公司现金流时，最初计划可能按季度计算；发现其中一家公司只披露半年数据后，应修订对齐方法并说明可比性，而不是继续填满原表。计划要保存“为什么改”，才能区分正常学习与任务漂移。\n\n可操作的计划包含目标、验收项、当前步骤、依赖、待确认事实和预计成本。每完成一个实质步骤，就将产物与验收项关联；新证据推翻假设时，保留旧版本和变更理由。工具异常只应修订受影响路径，避免每次小错误都重新生成整份计划，造成额外延迟和不稳定。\n\n计划不应拥有扩权能力。模型写下“联系客户确认”并不意味着已经获准发送；工作流仍检查当前授权。测试可安排一个中途出现矛盾证据的任务，观察Agent是否保留反证、调整后续步骤并维持原始限制。评价重点是计划是否帮助得到更好的结果，而不是计划文字是否完整或子任务数量是否丰富。\n\n可先用两种方案做同任务对照：直接循环和维护短计划的循环。记录新增正确证据、无效调用、人工修订和完成时间；若规划只让输出显得更有条理，却没有改善可验证结果，就减少规划粒度。计划的存在不应强迫模型先做形式化步骤，更不应成为继续一个明显错误方向的理由。\n\n**实践重点**：保存目标、依赖与未决问题；当证据改变假设时允许改计划。\n\n**验证抓手**：用资料冲突与工具失败场景检查计划是否有效修订。\n\n**常见误区**：把首次计划当承诺，或独立planner只增加无效轮次。\n\n[Anthropic：Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)；[Anthropic：长期任务Harness](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)。",
      "blueprint": {
        "inputs": [
          "目标与验收项",
          "已有证据和不确定性",
          "时间与成本预算"
        ],
        "steps": [
          "拆出可检查子结果",
          "执行并回填产物",
          "识别假设变化",
          "保存再规划理由"
        ],
        "outputs": [
          "版本化计划",
          "未决问题清单",
          "与验收关联的进度"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/building-effective-agents",
          "label": "Anthropic：Building effective agents",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents",
          "label": "Anthropic：长期任务Harness",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": [
        {
          "target": "agent-loop",
          "type": "requires",
          "reason": "本节点的设计需要先明确Agent执行循环。"
        }
      ]
    },
    {
      "id": "products-personal",
      "title": "持续个人Agent",
      "en": "Persistent Personal Agents",
      "aliases": [],
      "kind": "branch",
      "parentId": "products",
      "order": 40,
      "summary": "理解持续身份、多任务、云电脑和私人状态的产品合同。",
      "question": "怎样按技术路线和控制边界比较持续个人Agent？",
      "body": "持续个人Agent展示了从单次聊天到长期协调的产品方向，但它们首先是消费或工作产品，不等于开放企业framework。隔离单位可以是用户、账号、角色、Task或VM，必须按公开资料分别判断。借鉴任务与权限体验，不推断隐藏runtime、数据库或训练机制。\n\n[OpenAI dots：Tasks and memory](https://learn.chatgpt.com/docs/dots/tasks-and-memory)；[Grok Bot：角色与共享状态](https://docs.x.ai/grok-bot/bots)；[Meta：Muse安全工程设计](https://research.meta.ai/blog/security-and-safety-for-ai-agents-our-approach-with-muse)。",
      "blueprint": {
        "inputs": [
          "长期目标与连接",
          "任务和私人状态"
        ],
        "steps": [
          "辨别身份及隔离单位",
          "检查任务和memory合同",
          "核验共享及删除语义",
          "区分产品与开发接口"
        ],
        "outputs": [
          "持续协作模式",
          "公开边界与未知"
        ]
      },
      "citations": [
        {
          "url": "https://learn.chatgpt.com/docs/dots/tasks-and-memory",
          "label": "OpenAI dots：Tasks and memory",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://docs.x.ai/grok-bot/bots",
          "label": "Grok Bot：角色与共享状态",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://research.meta.ai/blog/security-and-safety-for-ai-agents-our-approach-with-muse",
          "label": "Meta：Muse安全工程设计",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": []
    },
    {
      "id": "release-manifest",
      "title": "运行版本清单",
      "en": "Release Manifest",
      "aliases": [
        "执行版本清单",
        "可复现配置"
      ],
      "kind": "concept",
      "parentId": "models-release",
      "order": 40,
      "summary": "记录一次执行所依赖的模型、规则、工具与数据版本。",
      "question": "怎样设计运行版本清单，并验证其对任务质量与可靠性的影响？",
      "body": "记录一次执行所依赖的模型、规则、工具与数据版本。\n\n运行版本清单把一次结果关联到实际执行条件。只记录model ID或prompt名称不足以重现Agent，因为SDK、工具、检索、memory政策和验证器都可能变化。清单是追踪与发布合同，不是保证模型随机输出逐字相同的承诺。\n\n发布时固定的配置包括provider、模型ID或snapshot、推理和采样设置、prompt模块hash、runtime commit、工具schema、workflow、memory政策、检索器配置、verifier与sandbox镜像。动态数据另按Run记录corpus/index generation、source_version、as_of和授权代次；不能为了冻结发布而冻结ACL或继续使用已撤回资料。\n\n输入记录可保存受限快照和内容引用，不需把敏感全文复制进每条日志。产物回溯时应能定位当时实际渲染的prompt、用过的证据、计算工具版本和审批参数。若外部源无法完整留存，明确可复现范围及读取日期，不能把当前页面内容冒充当时证据。\n\n清单还应记录限制：供应商别名不可固定、某原生工具没有版本号、数据接口会追溯修订。对这些变化设哨兵和异常调查，而不是填一个看似精确但不存在的版本。缓存、路由与fallback也会影响执行，应纳入实际Run轨迹。\n\n升级与回滚必须考虑兼容性。旧runtime可能读不了新checkpoint，新工具可能改变字段含义，模型opaque context也可能不可迁移。应决定让在途任务沿旧版本结束，还是提供显式迁移；不能只把deployment指针改回去就声称所有状态已恢复。\n\n一个好的清单使审查者可以回答：这个结论基于哪份资料，哪个计算或模型生成，按哪条规则批准，验证过什么。它并不要求展示私有思维链，而是保留可供外部检查的输入与效果。\n\n清单应由系统在运行时生成，避免事后靠人工回忆填写。用户修订目标或权限改变时，追加新的状态边界而非覆盖原记录；这样才能区分历史事实与当前有效条件。\n\n**实践重点**：配置随发布固定；corpus/index generation、as_of与ACL按Run记录和重验。\n\n**验证抓手**：从trace还原模型参数、prompt、工具和证据版本。\n\n**常见误区**：把动态授权冻结，或只记模板名无法定位真实输入。\n\n[Codex：turn与step循环源码](https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/turn.rs#L454-L518)；[OpenCode：session_v2与消息表源码](https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/sql.ts#L22-L144)。",
      "blueprint": {
        "inputs": [
          "发布配置与依赖hash",
          "Run实际数据版本",
          "工具和验证结果"
        ],
        "steps": [
          "冻结静态依赖",
          "记录动态数据generation",
          "关联输入及效果证据",
          "检查迁移和回滚兼容"
        ],
        "outputs": [
          "运行manifest",
          "可追溯产物",
          "复现边界说明"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/turn.rs#L454-L518",
          "label": "Codex：turn与step循环源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/sql.ts#L22-L144",
          "label": "OpenCode：session_v2与消息表源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "agent-definition-version",
          "type": "requires",
          "reason": "本节点的设计需要先明确Agent定义与版本。"
        },
        {
          "target": "execution-run",
          "type": "requires",
          "reason": "本节点的设计需要先明确执行Run。"
        }
      ]
    },
    {
      "id": "retrieval-reliability",
      "title": "召回可靠性与证据",
      "aliases": [],
      "kind": "branch",
      "parentId": "retrieval",
      "order": 40,
      "summary": "过滤条件、表示版本和证据选择会改变检索质量，即使底层向量算法没有变化。",
      "question": "怎样保证召回结果可用于可靠回答？",
      "body": "过滤条件、表示版本和证据选择会改变检索质量，即使底层向量算法没有变化。可靠性需要同时检查授权子集召回、embedding与索引兼容，以及最终证据的覆盖和引用身份。\n\n这一组页面解释ANN过滤、双索引迁移和证据组装。只返回足够数量或保持接口成功率不足以验收；应知道候选为什么出现、哪一版本被使用，以及权限或资料撤回之后如何停止供应。",
      "blueprint": {
        "inputs": [
          "任务问题与可用资料"
        ],
        "steps": [
          "过滤条件、表示版本和证据选择会改变检索质量，即使底层向量算法没有变化",
          "沿子节点选择合适机制"
        ],
        "outputs": [
          "可验证的检索设计选择"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/pgvector/pgvector",
          "label": "官方机制与实现参考",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "runtime-tools",
      "title": "工具、授权与协议",
      "en": "Tools Authorization and Protocols",
      "aliases": [],
      "kind": "branch",
      "parentId": "runtime",
      "order": 40,
      "summary": "把模型行动请求转换为有身份、可验证的业务操作。",
      "question": "怎样从工具、授权与协议进入可实施的设计与验证？",
      "body": "工具是模型与现实系统之间的接口。schema说明参数，网关决定授权，操作账本跟踪效果；这些层不能互相替代。大量工具可用发现机制缩小context，程序化调用可减少往返，MCP和A2A可改善互通，但它们都不自动解决信任、幂等与履约。\n\n[Anthropic：Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use)；[MCP：安全建议](https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices)。",
      "blueprint": {
        "inputs": [
          "工具目录",
          "当前身份与资源"
        ],
        "steps": [
          "发现并校验能力",
          "授权具体动作",
          "记录提交与回执",
          "处理未知和重试"
        ],
        "outputs": [
          "受控外部效果",
          "协议连接",
          "可对账操作"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/advanced-tool-use",
          "label": "Anthropic：Advanced tool use",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices",
          "label": "MCP：安全建议",
          "kind": "standard",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": []
    },
    {
      "id": "semantic-answer-cache",
      "title": "语义答案缓存",
      "en": "Semantic Answer Cache",
      "aliases": [
        "语义缓存",
        "答案缓存"
      ],
      "kind": "concept",
      "parentId": "performance-cache",
      "order": 40,
      "summary": "按问题语义复用最终答案，需满足相同业务条件。",
      "question": "怎样设计语义答案缓存，并验证其对任务质量与可靠性的影响？",
      "body": "按问题语义复用最终答案，需满足相同业务条件。\n\n语义答案缓存通过问题相似度复用最终回答，风险高于前缀或检索缓存。两个问题措辞接近，可能对应不同截止日、法域、币种、客户matter或学习阶段。答案内容一旦越过scope，后续生成再流畅也无法修复授权与适用性错误。\n\n可从低风险公共静态内容开始，例如已发布产品使用说明，并绑定明确文档版本与适用范围。动态金融判断、法律研究和针对具体学生的反馈不宜默认跨用户复用。设计上先做条件匹配和权限检查，语义相似度只是召回候选，不能直接决定可用。\n\n答案对象应带依赖来源、生成和验证版本、as_of、有效期、范围与未知项。使用前检查依赖仍有效，并重新鉴权；来源修订、删除、规则变化或模型策略更新时按lineage失效。只给答案一个固定十分钟TTL，无法覆盖即刻撤回权限或错误法域。\n\n个性化内容还可能包含用户偏好、学生观察或客户信息。去掉姓名并不一定足够匿名，答案中的具体情境也可能泄漏。缓存隔离应由运行时scope决定，模型不能自行指定另一个用户的键。对消费产品式个性化能力与企业共享知识，应保持不同边界。\n\n检验时专门构造“语义相似、关键条件不同”的反例，例如同一问题分别问美国和中国法、同一家公司在不同信息截止点的估值、两个学生对同一道题的不同误解。缓存必须拒绝错误复用，而不是只追求命中。\n\n成本评估包含验证与失效维护，以及错误答案带来的返工。若每次都需重新检索和专家复核才能确认安全，直接生成可能更简单。答案缓存是有适用边界的优化，不是Agent能力或长期记忆的替代。\n\n**实践重点**：优先低风险静态公共内容；绑定日期、法域、权限与依赖。\n\n**验证抓手**：测语义相似但条件不同的反例，并验证最终授权。\n\n**常见误区**：语义近似却混淆学生、币种、法域或金融时间点。\n\n[Anthropic：Context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)；[MCP：安全建议](https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices)。",
      "blueprint": {
        "inputs": [
          "相似问题候选",
          "业务条件和身份",
          "答案依赖及验证版本"
        ],
        "steps": [
          "匹配日期法域和scope",
          "重新鉴权与检查依赖",
          "验证可复用范围",
          "返回或拒绝命中"
        ],
        "outputs": [
          "适用答案",
          "复用理由",
          "错误命中与陈旧指标"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents",
          "label": "Anthropic：Context engineering",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices",
          "label": "MCP：安全建议",
          "kind": "standard",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "cache-invalidation",
          "type": "requires",
          "reason": "本节点的设计需要先明确缓存依赖失效。"
        },
        {
          "target": "completion-contract",
          "type": "requires",
          "reason": "本节点的设计需要先明确任务完成合同。"
        }
      ]
    },
    {
      "id": "storage-operations",
      "title": "托管与容量",
      "aliases": [],
      "kind": "branch",
      "parentId": "storage",
      "order": 40,
      "summary": "容量不仅是向量本体，还包含原件、索引、副本、日志、备份以及迁移临时空间。",
      "question": "云采购与容量怎样成为可验证的合同？",
      "body": "容量不仅是向量本体，还包含原件、索引、副本、日志、备份以及迁移临时空间。采购也不仅是接口价格，还涉及目标区域、可用阶段、资料用途与恢复能力。\n\n这一组将公式估算与真实负载测试结合，并把云产品版本条件显式化。先证明检索质量、撤回、导出和恢复，再决定是否扩大部署，避免用低空载延迟推断生产SLO。",
      "blueprint": {
        "inputs": [
          "数据与运行要求"
        ],
        "steps": [
          "明确该层职责与约束",
          "按子节点比较并验证"
        ],
        "outputs": [
          "可追溯的数据层决定"
        ]
      },
      "citations": [
        {
          "url": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors-metadata-filtering.html",
          "label": "官方机制与实现参考",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "structured-output",
      "title": "结构化输出",
      "en": "Structured Output",
      "aliases": [
        "JSON Schema",
        "结构化生成"
      ],
      "kind": "concept",
      "parentId": "models-contracts",
      "order": 40,
      "summary": "让模型输出符合规定结构，再由应用校验语义。",
      "question": "怎样设计结构化输出，并验证其对任务质量与可靠性的影响？",
      "body": "让模型输出符合规定结构，再由应用校验语义。\n\n结构化输出把回答组织成应用能够处理的字段，但格式正确并不等于业务正确。JSON能解析、符合schema和符合事实，是三个层次。企业应决定每个字段的类型、含义、缺失行为和验证方式，而不是只要求模型“返回JSON”。\n\n供应商对严格schema的支持范围可能不同，一些关键字、联合类型、可选字段或原生工具组合需要独立验证。Pydantic等类型系统可帮助构建合同，但类型强制转换也可能掩盖输入错误。金额、日期、单位和枚举应有明确口径，不让字符串被宽松解释后悄悄改变含义。\n\n输出合同应容纳拒绝、证据不足、部分完成和截断，不能逼模型在未知时填看似合法的值。法律研究的citation字段要带原文定位与适用边界，财报指标带期间币种和公式，教学观察带证据与不确定性。一个字段叫confidence，并不意味着数值经过校准。\n\n应用先验证结构，再做确定性和语义检查。计算结果复算、资源存在、引用支持和权限检查可以独立执行；解释质量需校准judge或专家。修复schema错误要限次数，若修复改变了已批准的动作，应重新审批。不能为了通过parser而删除重要未知或错误状态。\n\n流式界面可逐步展示候选字段，但提交业务结果需要完整对象校验。模型输出到一半被中断，不能把缺少后半部分的对象当最终报告。保存原输出和修复轨迹，有助区分模型问题、adapter问题与schema设计问题。\n\n测试覆盖中文、时区、小数、极值、空列表、未知枚举、refusal和输出上限，并添加“结构合格但语义错”的反例。最终验收结合任务成功与严重错误，不能用schema通过率替代Agent质量。\n\n面向用户的最终展示应保留不确定性，不能在排版时删掉结构中的unknown或证据不足字段。\n\n**实践重点**：区分JSON可解析、schema合规与业务正确；拒绝和截断是独立状态。\n\n**验证抓手**：测试中文、日期、数值、enum、refusal与不完整输出。\n\n**常见误区**：格式正确就默认金额、引用或学生评分正确。\n\n[OpenAI Agents SDK：模型与provider](https://developers.openai.com/api/docs/guides/agents/models)；[Pydantic AI：Harness能力边界](https://pydantic.dev/docs/ai/harness/)。",
      "blueprint": {
        "inputs": [
          "输出字段与业务含义",
          "模型schema能力",
          "事实与权限验证器"
        ],
        "steps": [
          "生成完整对象",
          "校验schema和缺失状态",
          "复算并检查证据",
          "提交或限次修复"
        ],
        "outputs": [
          "类型化产物",
          "字段级验证结果",
          "明确拒绝和未知"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/agents/models",
          "label": "OpenAI Agents SDK：模型与provider",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://pydantic.dev/docs/ai/harness/",
          "label": "Pydantic AI：Harness能力边界",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "model-adapter",
          "type": "requires",
          "reason": "本节点的设计需要先明确模型适配层。"
        },
        {
          "target": "tool-contract",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具接口合同。"
        }
      ]
    },
    {
      "id": "cache-invalidation",
      "title": "缓存依赖失效",
      "en": "Cache Invalidation",
      "aliases": [
        "依赖失效",
        "缓存撤回"
      ],
      "kind": "concept",
      "parentId": "performance-cache",
      "order": 50,
      "summary": "让源、授权与策略变化传播到相关缓存和在途结果。",
      "question": "怎样设计缓存依赖失效，并验证其对任务质量与可靠性的影响？",
      "body": "让源、授权与策略变化传播到相关缓存和在途结果。\n\n缓存失效是数据和权限治理的一部分。来源更新、删除、ACL与群组变化、memory撤回、模型和prompt更新、索引切换与时间跨界，都可能让旧结果不再适用。TTL只能控制一段最长复用时间，不能替代这些事件传播。\n\n建议维护依赖链：缓存结果依赖哪些source_version、资源、权限代次和策略。源事件触发相关键失效，写入新generation后再原子切换可读指针，减少新旧索引混用。对于无法精确追踪的依赖，可采用更粗范围失效，但应评估重建负载和冷启动影响。\n\n权限撤回尤其需要处理在途信息。资料可能已经进入当前context、摘要、子Agent和待发布产物。清掉检索缓存并不会让模型忘记已见内容；应使受影响Run失效、取消或受控重建context，最后发布前再次检查来源资格。删除日志payload也不能当成撤回所有下游副本的证明。\n\nPrefix cache由供应商控制，应用未必能逐条删除；这与自有检索或答案缓存不同。采购时核对保留、隔离和删除合同，不把本地清空等同云端零保留。业务侧可以停止继续发送旧前缀，并治理可控制的副本和引用。\n\n失效事件可能密集发生，需有去重、重试和背压。避免每次小更新触发全库重算，也不能为降低成本而忽略关键ACL事件。缓存owner、依赖版本和最后校验时间应可观测。\n\n测试撤销群组权限、删除文档、更新法条有效期、撤回学生观察和切换模型规则，检查从候选到产物的传播。验收不只看键是否消失，还看旧内容是否仍在prompt、子任务或最终回答里出现。失效正确性比单一命中率更能决定企业可信度。\n\n**实践重点**：按lineage失效；撤回资料时重建受影响context并复核待发布产物。\n\n**验证抓手**：覆盖源删除、群组变化、memory撤回与索引切换。\n\n**常见误区**：只等TTL或只清索引，忽略已有摘要和子Agent。\n\n[Claude Code：Prompt caching](https://code.claude.com/docs/en/prompt-caching)；[MCP：安全建议](https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices)。\n\n失效处理应有可查询状态和失败告警。关键撤回事件未传播完成前，相关高风险发布可暂缓，而不是默认继续读取旧副本。",
      "blueprint": {
        "inputs": [
          "源与授权变更事件",
          "缓存和产物依赖图",
          "在途Run及context引用"
        ],
        "steps": [
          "定位受影响依赖",
          "失效键和旧generation",
          "重建或停止在途输入",
          "发布前重新核查"
        ],
        "outputs": [
          "有效缓存集合",
          "在途处理记录",
          "可验证撤回结果"
        ]
      },
      "citations": [
        {
          "url": "https://code.claude.com/docs/en/prompt-caching",
          "label": "Claude Code：Prompt caching",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices",
          "label": "MCP：安全建议",
          "kind": "standard",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "event-log",
          "type": "requires",
          "reason": "本节点的设计需要先明确事件日志。"
        },
        {
          "target": "tool-authorization",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具授权网关。"
        }
      ]
    },
    {
      "id": "context-compaction",
      "title": "上下文压缩",
      "en": "Context Compaction",
      "aliases": [
        "上下文压缩",
        "自动摘要"
      ],
      "kind": "concept",
      "parentId": "runtime-harness",
      "order": 50,
      "summary": "以摘要或提供商原生状态降低活跃上下文占用。",
      "question": "怎样缩短上下文而保留限制、证据和未完成动作？",
      "body": "以摘要或提供商原生状态降低活跃上下文占用。\n\n压缩解决的是活跃窗口容量，不是把所有历史变成永久事实。常见方式是保留近期原文、将较早内容总结，或使用供应商原生压缩状态。原始事件与产物应仍可回查；摘要是用于下一步推理的视图。金融数值、法律引证和待执行承诺尤其不能只剩一段自由文本概述。\n\nCodex公开源码将后台压缩尝试绑定history_version、model_slug、compaction_hash与授权代次。只有结果仍与当前状态兼容时才可采用。这提示异步压缩存在竞态：用户补充了新限制、切换模型或权限发生变化后，刚完成的旧摘要未必有效。OpenCode研发源码则区分summary、近期原文与provider原生context，显示不同压缩策略需要不同迁移合同。\n\n压缩输入应明确已完成与未完成范围，并保留原目标、用户修订、否定条件、证据指针、审批参数、操作状态和资源版本。当前授权必须从服务端重新获得，摘要里的权限只能作为历史记录。压缩后应检查这些不变量；不能为腾出空间删掉“尚未发送”中的否定词，再把草稿当已交付。\n\n换模型时，opaque reasoning或compaction token可能无法跨供应商解释，应从可移植事件与证据重新构造上下文。压缩本身还会产生模型调用与缓存重建成本。可在自然任务边界执行，避免频繁压缩造成抖动。验证使用同一长任务的压缩前后对照，检查约束、引用和副作用状态，而不是只看摘要长度是否下降。\n\n对关键字段可建立压缩检查表：当前公司和报表期、使用的合同版本、用户禁止动作、尚未完成的批准以及最近一次外部操作状态。检查表从结构化状态生成，再与摘要对照。若不一致，就重新构造输入或回到原事件，不能让模型用措辞更顺的摘要覆盖可验证记录。\n\n**实践重点**：原始事件保持可回查；摘要带来源范围、模型与版本；换模型先检查兼容性。\n\n**验证抓手**：比较压缩前后目标、待审批动作、数值与证据指针不变量。\n\n**常见误区**：把摘要当原始事实，或把过期后台压缩结果用于新历史。\n\n[Codex：异步压缩兼容性源码](https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/async_compaction.rs#L23-L117)；[OpenCode：摘要与近期原文](https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/compaction.ts#L705-L743)。",
      "blueprint": {
        "inputs": [
          "历史事件范围",
          "当前模型能力",
          "目标、约束和待执行状态"
        ],
        "steps": [
          "选择近期原文和可总结历史",
          "生成带版本摘要",
          "校验历史及授权代次",
          "测试约束和证据不变量"
        ],
        "outputs": [
          "可回查摘要",
          "保留原文窗口",
          "兼容性与压缩记录"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/async_compaction.rs#L23-L117",
          "label": "Codex：异步压缩兼容性源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        },
        {
          "url": "https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/compaction.ts#L705-L743",
          "label": "OpenCode：摘要与近期原文",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        }
      ],
      "links": [
        {
          "target": "event-log",
          "type": "requires",
          "reason": "本节点的设计需要先明确事件日志。"
        },
        {
          "target": "context-assembly",
          "type": "requires",
          "reason": "本节点的设计需要先明确上下文组装。"
        }
      ]
    },
    {
      "id": "event-log",
      "title": "事件日志",
      "en": "Event Log",
      "aliases": [
        "事件溯源",
        "执行日志"
      ],
      "kind": "concept",
      "parentId": "runtime-task-session",
      "order": 50,
      "summary": "记录意图、执行、结果与验证状态的有序事件历史。",
      "question": "怎样保存能够重建状态的记录，并区分声明与效果？",
      "body": "记录意图、执行、结果与验证状态的有序事件历史。\n\n事件日志记录系统观察到的意图、执行与结果，不能把所有payload都当成已验证事实。模型说“邮件已发送”、工具返回“请求已受理”、外部系统出现投递回执，是不同事件。记录这种差别，才能回放状态并解释任务为何被判成功或结果未知。\n\nOpenCode固定研发源码把Session、顺序消息、pending和inbox拆成不同表，使用唯一顺序索引。DeepSeek Harness公开loop从session日志派生下一请求。实现方式可以不同，但都提醒持久历史需要稳定身份、顺序和可解释边界，而不是一个不断覆盖的聊天字符串。\n\n业务事件建议包括event_id、序号、actor、父事件、Task/Run引用、操作ID、时间、schema版本和payload引用。工具意图先写入，再发生副作用；成功与失败回执随后追加。摘要是projection，状态可从已提交事件重建。不能只保存流式token而没有最终tool状态，也不能让客户端将临时文字直接写成task.completed。\n\n不可变追加不等于永远保留所有敏感内容。payload可独立加密和按策略删除，日志保留最小必要的删除证明；访问调试内容也要权限与审计。保留期与采样影响可回放范围，应公开为运维合同。测试检查重复事件去重、乱序回调、schema升级和payload删除后状态解释，尤其避免流式快照导致无界存储放大。\n\n一个最小事件链可以是操作请求、授权通过、外部提交、回执确认、后置验证。它们必须允许中间停在unknown，而非强迫每条请求立即出现成功或失败。回放器只依据明确事件转换状态，不从自然语言“应该已经完成”推断事实；这也使事件schema升级更容易审查。\n\n事件时间也应区分发生、接收和提交，延迟回调不能以到达顺序改写事实先后。跨服务可用相关ID串联，不必把所有敏感原文复制到一个全局日志。\n\n**实践重点**：区分模型声明、工具回执和验证结论；敏感payload独立保留。\n\n**验证抓手**：按序回放可重建状态；删除payload后保留最小必要证明。\n\n**常见误区**：日志里出现成功文字就视为真实外部效果。\n\n[OpenCode：session_v2与消息表源码](https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/sql.ts#L22-L144)；[DeepSeek Harness：事件日志驱动循环](https://github.com/deepseek-ai/deepseek-harness/blob/86a402200d95fecef4529d969836f1fe13c6cb0d/packages/core/agent-loop/src/agent.ts#L42-L168)。",
      "blueprint": {
        "inputs": [
          "模型与工具事件",
          "Task、Run及操作身份",
          "保留与访问策略"
        ],
        "steps": [
          "预写操作意图",
          "按序提交结果事件",
          "生成可重建projection",
          "治理payload保留和删除"
        ],
        "outputs": [
          "权威事件序列",
          "状态投影",
          "可审计证据链"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/sql.ts#L22-L144",
          "label": "OpenCode：session_v2与消息表源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        },
        {
          "url": "https://github.com/deepseek-ai/deepseek-harness/blob/86a402200d95fecef4529d969836f1fe13c6cb0d/packages/core/agent-loop/src/agent.ts#L42-L168",
          "label": "DeepSeek Harness：事件日志驱动循环",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        }
      ],
      "links": [
        {
          "target": "execution-run",
          "type": "requires",
          "reason": "本节点的设计需要先明确执行Run。"
        }
      ]
    },
    {
      "id": "incident-recovery-runbooks",
      "title": "故障止损与恢复手册",
      "en": "Incident recovery runbooks",
      "aliases": [
        "Runbook",
        "事故响应",
        "降级恢复"
      ],
      "kind": "concept",
      "parentId": "operations",
      "order": 50,
      "summary": "把告警转为具体止损、对账、恢复与重新验收动作。",
      "question": "故障发生后，怎样证明可以安全恢复？",
      "body": "## 手册是一份动作合同\n每类事故指定触发条件、owner、影响范围、允许止损动作、恢复前置和完成证据。记录Task／Run、发布版本、来源及外部操作身份。告警看板只定位症状，不能替代手册；也不要让处理事故的Agent自由扩大权限。\n\n## 按故障边界止损\n模型不可用或限流时停止无上限重试，按截止时间排队；回退模型先检查能力和数据资格。索引落后时披露资料时间，必要时切回权威数据或暂停依赖新鲜度的回答。验证器不可用时保留候选，不把“检查服务失败”转为“结果通过”。\n\n外部工具效果未知时固定operation_id，停止自动重放，查询目标权威状态或进入人工对账。取消Run只阻止后续动作，已发生效果需单独确认或补偿。撤权时沿来源血缘失效上下文、子任务和待交付产物；记忆投毒时隔离受影响scope与写入版本，保留取证引用，恢复到经审查状态后重测。\n\n## 恢复要证明什么\n分别确认服务恢复、数据追平、无重复外部效果、权限有效和产物重新验证。每个恢复报告绑定实际状态与检查时间，不能只写“worker已重启”。如回滚模型但保留了受污染记忆，或回滚代码却无法读取在途checkpoint，系统仍未恢复。\n\n## 演练与复盘\n在测试环境注入限流、丢回调、旧worker复活、索引延迟和恶意记忆。检查告警路由、人工等待、对账结果及回滚可执行性。复盘区分触发原因、放大路径与缺失控制，将可复现失败进入回归集；失败轨迹作为诊断材料，不直接当作SFT正样本。上述是参考手册结构，具体阈值与责任人必须由部署方根据任务风险和实际运行证据设定。",
      "blueprint": {
        "inputs": [
          "告警与受影响Task/Run",
          "当前发布和外部操作身份"
        ],
        "steps": [
          "限制新增效果并确定影响范围",
          "核查权威状态与数据血缘",
          "按手册恢复并重跑门禁"
        ],
        "outputs": [
          "外部状态对账回执",
          "恢复报告与回归案例"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/open-telemetry/semantic-conventions-genai",
          "label": "OpenTelemetry：GenAI运行观测约定",
          "kind": "code"
        },
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent评测与故障诊断",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "unknown-operation-outcome",
          "type": "requires",
          "reason": "恢复未知副作用前先对账外部状态。"
        },
        {
          "target": "revocation-lineage",
          "type": "requires",
          "reason": "数据或权限事故沿血缘定位在途影响。"
        },
        {
          "target": "eval-release-rollback",
          "type": "requires",
          "reason": "恢复需兼容完整版本与持久状态。"
        },
        {
          "target": "eval-trial-replay",
          "type": "requires",
          "reason": "可复现故障进入明确初态的回归试验。"
        }
      ]
    },
    {
      "id": "knowledge",
      "title": "知识来源与生命周期",
      "aliases": [
        "knowledge base",
        "enterprise knowledge",
        "企业知识库"
      ],
      "kind": "domain",
      "parentId": null,
      "order": 50,
      "summary": "权威组织知识及其来源、版本、可见性和领域数据合同。",
      "question": "哪些组织资料可以被信任、更新和撤回？",
      "body": "企业知识的核心是有来源、版本、可见范围和有效时间的组织记录。文件内容、正式制度、聊天转述和模型推断必须保留不同身份；即使它们被转换成相似的文本或向量，也不因此拥有相同权威性。\n\n这一分支沿资料生命周期展开：先明确连接器的对象与变化合同，再恢复文档结构，保存原件及派生来源链，最后处理增量发布、权限和删除。检索引擎消费这些记录，但不应成为唯一事实来源。一个可删除、可审计的知识系统，需要能够从答案回到某一版原件，也能够从撤回事件找到所有派生物。\n\n金融资料还要限制当时可知信息，法律资料要限制法域和效力，教育产品要分开课程知识与学生状态。三个领域的数据合同在本分支定义；完整任务流程、生成行为和领域效果评估由对应场景节点展开。",
      "blueprint": {
        "inputs": [
          "组织资料与源授权",
          "版本、时间和用途合同"
        ],
        "steps": [
          "接入并恢复结构",
          "建立来源与活动版本",
          "传播授权、撤回与删除"
        ],
        "outputs": [
          "可检索的授权知识",
          "可追溯证据与生命周期状态"
        ]
      },
      "citations": [
        {
          "url": "https://learn.microsoft.com/en-us/graph/api/driveitem-delta?view=graph-rest-1.0",
          "label": "Microsoft Graph：变化同步",
          "kind": "official-doc"
        },
        {
          "url": "https://github.com/docling-project/docling",
          "label": "Docling：文档结构",
          "kind": "code"
        }
      ],
      "links": []
    },
    {
      "id": "knowledge-source-connectors",
      "title": "连接器与源系统合同",
      "aliases": [
        "connector",
        "delta token",
        "change feed"
      ],
      "kind": "concept",
      "parentId": "knowledge-ingestion",
      "order": 50,
      "summary": "源对象ID、游标、全量对账、速率限制、六类生命周期事件。",
      "question": "什么样的数据源能可靠接入企业知识库？",
      "body": "### 连接器的产物是一组可同步的对象\n\n企业资料接入的单位应是有稳定身份的源对象，而不是某次下载得到的一段文字。文件重命名、移动、修改内容和权限收紧可能同时发生；若以路径或标题作为唯一键，就会产生重复记录，并把旧对象遗留在索引里。建议以source system与source object ID建立身份，路径只作为可变属性。\n\nMicrosoft Graph的driveItem delta体现了这种接口合同：先完成分页枚举，再保存deltaLink获取后续变化；删除对象带deleted标记。官方还说明旧token可能失效并要求重新同步。因此连接器需要维护完整游标状态和对账过程，不能把一次HTTP成功等同于完成同步。其他资料源的变化语义须分别核查。\n\n### 准入与恢复\n\n接入前逐项确认六类事件：创建、内容更新、移动或改名、权限变化、归档、删除。记录资料所有者、访问范围、更新时间、是否允许二次分发与训练，以及限流和回填方式。若连接器读不到源系统的精细权限，只能用于明确开放的资料域。\n\n同步任务宜按源对象幂等处理，保存最近确认的游标和处理结果；只有一批变化已经可靠写入，才能推进消费位置。发现游标失效时重新枚举，并比较现有对象，不能直接清空在线知识库。长期没有变化的对象也应接受周期对账，以捕获漏掉的删除和授权变化。\n\n验收应刻意制造分页中断、重复事件、对象移动、token失效和漏通知，确认恢复后既不丢对象，也不制造重复版本。最终产物应同时回答两个问题：这一批资料是否已完整接入，以及其中哪些对象已经可供当前用户检索。",
      "blueprint": {
        "inputs": [
          "源系统与对象身份",
          "增量游标、权限与使用合同"
        ],
        "steps": [
          "完成分页枚举并保存快照",
          "幂等处理六类生命周期事件",
          "推进游标并定期全量对账"
        ],
        "outputs": [
          "可追溯源对象清单",
          "同步位置与异常队列"
        ]
      },
      "citations": [
        {
          "url": "https://learn.microsoft.com/en-us/graph/api/driveitem-delta?view=graph-rest-1.0",
          "label": "Microsoft Graph：driveItem delta",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "knowledge-incremental-publishing",
          "type": "feeds",
          "reason": "连接器事件驱动增量发布"
        },
        {
          "target": "knowledge-acl-propagation",
          "type": "requires",
          "reason": "连接器必须读到源权限"
        }
      ]
    },
    {
      "id": "memory-operations",
      "title": "迁移与运维",
      "aliases": [],
      "kind": "branch",
      "parentId": "memory",
      "order": 50,
      "summary": "记忆服务长期运行时，抽取器、压缩器、生成模型和检索表示都可能改变。",
      "question": "模型变化后怎样保持记忆合同？",
      "body": "记忆服务长期运行时，抽取器、压缩器、生成模型和检索表示都可能改变。原始证据与模型无关schema应允许复核与重建，发布配置则记录每个兼容轴。\n\n本组聚焦升级与回归，避免把最终任务总分当作唯一诊断。先检查事实是否存在、检索是否返回、模型能否使用，再做影子与灰度；回滚也不能恢复已经撤回的事实和权限。",
      "blueprint": {
        "inputs": [
          "记忆合同和任务需要"
        ],
        "steps": [
          "按子节点选择机制",
          "验证跨Session效果与边界"
        ],
        "outputs": [
          "可维护的记忆设计"
        ]
      },
      "citations": [
        {
          "url": "https://help.getzep.com/v4/agent-memory-solution",
          "label": "官方机制与实现参考",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "microsoft-agent-framework",
      "title": "Microsoft Agent Framework",
      "en": "Microsoft Agent Framework",
      "aliases": [
        "MSAF",
        "MAF",
        "Microsoft Agent Framework"
      ],
      "kind": "product",
      "parentId": "products-frameworks",
      "order": 50,
      "summary": "面向Python与.NET的Agent和多Agent工作流框架。",
      "question": "它怎样运行Agent，哪些状态和权限仍由应用负责？",
      "body": "观察时点：2026-10-15。面向Python与.NET的Agent和多Agent工作流框架。\n\n## 已公开的技术路线与控制边界\n\n多provider、图工作流、middleware、checkpoint、streaming及hosting集成。应用与托管服务分层；企业身份、数据权限和业务验证仍需明确实现。\n\nMicrosoft Agent Framework面向Python与.NET团队构建Agent和多Agent工作流。当前README列出多provider、图编排、middleware、checkpoint、streaming和hosting方向，并提供从Semantic Kernel与AutoGen迁移的入口。新项目应核实当前框架，而非直接照搬旧教程中的默认路线。\n\n对既有.NET、Azure或Foundry团队，语言、身份与部署生态可能减少接入成本；这是一项工程适配优势，不是金融或法律准确率证明。应用仍需要自己的领域工具、Task合同、证据、权限和verifier。Azure托管能力、开源库与非Azure模型的运行合同要分别看。\n\n工作流可表达顺序、并行、handoff和协作，模型负责局部探索。多Agent模式增加的是分工和合并责任，不应成为默认复杂度。对子任务定义scope、预算与结构化产物，对共享写入使用owner、锁或版本。能够并发运行多个Agent，不意味着外部系统自动具备事务和幂等。\n\n状态与持久化扩展提供实施入口，但企业长期memory仍需来源、过期、删除和租户治理。部署后端也可能决定等待、恢复和日志行为。本次读取README和MIT文件，未完成每种hosting及provider的运行测试；不能把“production-grade”自述直接升级为本项目生产验证。\n\n选择框架时，可先复用团队熟悉的身份和云运维能力，再以相同业务任务比较LangGraph或typed Python路线。不要为了统一品牌重写已可用的领域接口，也不要把模型、工作流和数据服务全部绑定到某个私有类型。清楚的数据导出和退出路径仍有价值。\n\nPoC覆盖checkpoint与外部效果、人工等待、取消、模型切换和部署升级，分别报告各provider兼容与领域质量。凭证初始化和刷新也进入延迟与权限测试，开发期方便的自动探测路径不必然适合生产。最终采用依据是目标环境中可重复的成功与维护成本，而非功能清单长度。\n\n一条适合既有企业栈的试验路径，是让身份系统生成受信主体，由middleware注入允许的工具和项目scope，工作流串起证据收集、复核与批准。金融或法律工具返回有版本的证据对象，模型只负责理解与综合；正式发送或写入保持独立批准。对Azure与非Azure模型分别运行相同契约样例，比较stream、schema、token计量和错误映射。语言统一和云托管可以降低部分维护，但不能消除数据源、长期memory与业务事务的差异。把这些责任显式列出，才能准确计算复用成本。\n\n## 数据、记忆与模型替换\n\n提供状态与持久化扩展；业务memory与跨租户scope需按后端核验。\n\nREADME明确多provider；Azure/Foundry原生能力和非Azure模型分别测试。\n\n## 执行、部署与采用取舍\n\nPython或.NET应用及所选hosting执行；各模型服务独立。图工作流支持多种协作模式，并提供middleware等扩展。自有云服务或Foundry等hosting路线按当前接口核验。\n\n适合既有.NET/Azure团队复用身份、运维和开发经验。\n\n观察于2026-10-15：Python与.NET发布及hosting能力分别核实；Python 1.22.0；SHA deecbcb062198f926516f89b65e5b1676e4514c2\n\n许可边界：MIT。采用前按实际使用方式核验组件、云服务与模型条款。\n\n## 证据范围与未知\n\n固定README和MIT许可已核，含从Semantic Kernel/AutoGen迁移入口。\n\n未公开或仍需目标环境验证的部分：部署后端完整行为；三域能力表现；特定provider兼容。本页不以产品表面行为推断其隐藏实现。\n\n[Microsoft Agent Framework：固定源码](https://github.com/microsoft/agent-framework/tree/deecbcb062198f926516f89b65e5b1676e4514c2)；[Microsoft Agent Framework：MIT许可](https://github.com/microsoft/agent-framework/blob/deecbcb062198f926516f89b65e5b1676e4514c2/LICENSE)。",
      "blueprint": {
        "inputs": [
          "Python或.NET任务定义",
          "Provider和hosting配置",
          "企业身份与领域工具"
        ],
        "steps": [
          "选择运行及身份后端",
          "定义图和局部Agent",
          "配置中间件与持久化",
          "验证多provider和恢复"
        ],
        "outputs": [
          "应用Agent及工作流",
          "状态和操作审计",
          "生态适配与维护比较"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/microsoft/agent-framework/tree/deecbcb062198f926516f89b65e5b1676e4514c2",
          "label": "Microsoft Agent Framework：固定源码",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://github.com/microsoft/agent-framework/blob/deecbcb062198f926516f89b65e5b1676e4514c2/LICENSE",
          "label": "Microsoft Agent Framework：MIT许可",
          "kind": "code",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": [
        {
          "target": "agent-workflow",
          "type": "implements",
          "reason": "公开能力或可见源码体现Workflow与局部Agent的具体产品路线。"
        },
        {
          "target": "model-adapter",
          "type": "complements",
          "reason": "用模型适配层检查采用时的控制边界；不推断未公开内部机制。"
        },
        {
          "target": "checkpoint-recovery",
          "type": "complements",
          "reason": "用Checkpoint与恢复检查采用时的控制边界；不推断未公开内部机制。"
        },
        {
          "target": "child-agent-contract",
          "type": "implements",
          "reason": "公开能力或可见源码体现子Agent委派合同的具体产品路线。"
        }
      ],
      "productRoute": {
        "vendor": "Microsoft",
        "category": "多语言Agent与Workflow框架",
        "execution": "Python或.NET应用及所选hosting执行；各模型服务独立。",
        "orchestration": "图工作流支持多种协作模式，并提供middleware等扩展。",
        "context": "Agent、middleware与workflow管理任务输入；不同provider能力分别核验。",
        "persistence": "提供状态与持久化扩展；业务memory与跨租户scope需按后端核验。",
        "modelBoundary": "README明确多provider；Azure/Foundry原生能力和非Azure模型分别测试。",
        "deployment": "自有云服务或Foundry等hosting路线按当前接口核验。",
        "license": "MIT",
        "availability": "观察于2026-10-15：Python与.NET发布及hosting能力分别核实；Python 1.22.0；SHA deecbcb062198f926516f89b65e5b1676e4514c2",
        "strengths": "适合既有.NET/Azure团队复用身份、运维和开发经验。",
        "limits": "待验证或未公开：部署后端完整行为；三域能力表现；特定provider兼容。公开能力不等同企业负载与领域任务实测。"
      }
    },
    {
      "id": "reasoning-budget",
      "title": "推理与行动预算",
      "en": "Reasoning and Action Budget",
      "aliases": [
        "推理预算",
        "Token预算"
      ],
      "kind": "concept",
      "parentId": "models-release",
      "order": 50,
      "summary": "限制推理强度、输出、工具轮次、时间和费用。",
      "question": "怎样设计推理与行动预算，并验证其对任务质量与可靠性的影响？",
      "body": "限制推理强度、输出、工具轮次、时间和费用。\n\n推理预算不只是一个reasoning effort参数。完整Agent还消耗输出token、工具轮次、搜索、重排、子Agent、judge、沙箱和人工复核时间。预算需要从业务目标出发，决定哪些问题值得继续投入，哪些达到上限后应返回缺口。\n\n可分别限制一次模型调用和整个Task。前者包含最大输出、推理强度和超时；后者包含总费用、总deadline、工具动作和子任务数量。剩余预算向下传播，使一个组件不会在外层即将超时后仍按默认上限重试。人工等待与活跃计算可使用不同时间口径，但需要明确。\n\n高风险任务不能简单以低成本为目标。可先用确定性计算替代可程序化算术，减少无效搜索与重复自评，再比较模型档位。增加推理强度可能改善困难理解，也可能增加延迟而不修复来源错误；缺少报表、法条或授权，更多推理不会创造事实。\n\n预算策略应允许有限升级。例如标准模型在无进展时可以换获准高档模型，但要保留数据合同和剩余费用；达到上限后保存已完成产物、验证项及未决问题，而非强行输出确定结论。模型显示的token使用量与实际账单分类还要核对，缓存写入和后台工作不能遗漏。\n\n实验绘制质量、严重错误、完成时间和有效结果成本随预算的变化，而不是只比较一次最快或最便宜运行。不同任务类型可能有不同折中；教学对话重视交互响应，异步研究可接受更长计算，但都需要真实验收。\n\n公开模型目录提供可调设置与价格入口，不能证明最佳预算。产品可以把预算表达为标准、深入或限定时长等可理解选择，内部再映射参数；不要让业务用户为每个底层推理开关承担实现决策。\n\n**实践重点**：按任务风险配置预算，并把剩余预算传给模型与工具执行器。\n\n**验证抓手**：测不同预算下质量、严重错误和完成成本曲线。\n\n**常见误区**：只调reasoning effort，忽略工具、judge和子Agent成本。\n\n[OpenAI：模型目录](https://developers.openai.com/api/docs/models)；[OpenAI：Latency optimization](https://developers.openai.com/api/docs/guides/latency-optimization)。",
      "blueprint": {
        "inputs": [
          "任务风险与价值",
          "模型及工具成本",
          "总deadline和费用上限"
        ],
        "steps": [
          "分配调用与任务预算",
          "传播剩余额度",
          "限次升级或改策略",
          "到限保留部分成果"
        ],
        "outputs": [
          "预算策略",
          "实际用量账本",
          "质量成本曲线"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/models",
          "label": "OpenAI：模型目录",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        },
        {
          "url": "https://developers.openai.com/api/docs/guides/latency-optimization",
          "label": "OpenAI：Latency optimization",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15；具体模型、版本和部署能力需分别核验。"
        }
      ],
      "links": [
        {
          "target": "model-routing",
          "type": "requires",
          "reason": "本节点的设计需要先明确模型路由。"
        },
        {
          "target": "deadline-propagation",
          "type": "requires",
          "reason": "本节点的设计需要先明确Deadline与剩余预算。"
        }
      ]
    },
    {
      "id": "retrieval-strategies",
      "title": "检索策略选择",
      "aliases": [],
      "kind": "branch",
      "parentId": "retrieval",
      "order": 50,
      "summary": "关系与全局主题、全量数值聚合、完整文档比较，对证据有不同要求。",
      "question": "不同问题应走哪一种知识路线？",
      "body": "关系与全局主题、全量数值聚合、完整文档比较，对证据有不同要求。GraphRAG、结构化查询和长上下文各自覆盖特定缺口，不能仅用一个top-k向量接口承诺全部任务。\n\n策略选择从真实失败集开始：先明确缺少的是关系、覆盖、计算还是全文约束，再比较额外成本与质量。常见组合是检索缩小范围后完整阅读，并让确定性工具处理数值。",
      "blueprint": {
        "inputs": [
          "任务问题与可用资料"
        ],
        "steps": [
          "关系与全局主题、全量数值聚合、完整文档比较，对证据有不同要求",
          "沿子节点选择合适机制"
        ],
        "outputs": [
          "可验证的检索设计选择"
        ]
      },
      "citations": [
        {
          "url": "https://microsoft.github.io/graphrag/query/overview/",
          "label": "官方机制与实现参考",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "storage-authority-derived",
      "title": "权威状态与派生索引",
      "aliases": [
        "source of truth",
        "derived index",
        "data plane"
      ],
      "kind": "concept",
      "parentId": "storage-architecture",
      "order": 50,
      "summary": "事务权威库/对象原件/检索索引/模型上下文的角色和数据归属。",
      "question": "哪些数据是系统真相，哪些可以丢掉后重建？",
      "body": "### 先分配真相，再选择引擎\n\nTask处于什么状态、用户拥有什么权限、文档哪一版有效，与某段文字向量最接近谁，是不同问题。事务数据库适合维护业务权威状态，对象存储保存原件和长产物，检索引擎保存可重建的倒排与向量索引；模型上下文则是一次调用的临时投影。\n\n这一划分是建议架构，不要求为每个角色部署独立产品。一个托管PostgreSQL可以同时保存状态、元数据和向量；随着工作负载变化再独立检索服务。重要的是知道丢失或冲突时，以哪一份记录为准，能否从原始证据重建派生物。\n\n### 显式定义一致性\n\n把状态和向量放在同库可减少跨库同步，但不免除版本、索引和授权问题。使用独立服务时，数据库事务与索引更新通常不能天然原子提交。AWS的outbox模式是维持业务变更与事件发布一致的一种方法，应用还需追踪消费进度和索引generation。\n\n建议为每类数据写出owner、更新权限、恢复来源、允许延迟、保留期和删除路径。原始消息与记忆抽取结果分开，执行checkpoint与自然语言摘要分开，正式制度与模型经验分开。只有这样，模型或框架替换时才能迁移显式合同，而非依赖隐藏状态。\n\n### 用故障判断架构是否成立\n\n可以故意丢弃检索索引并重建，确认不会丢失唯一原件或任务结果；让索引落后权威库，确认已撤回资料不能继续读取；恢复旧备份，确认新的tombstone和权限变更会重新应用。\n\n如果某条“派生”摘要已成为唯一事实来源，或者缓存故障导致审批状态消失，说明角色边界已经被破坏。验收应报告恢复时间、资料新鲜度与丢失窗口，而不是只证明平时读写接口返回成功。",
      "blueprint": {
        "inputs": [
          "数据类别与业务合同",
          "现有云服务和恢复要求"
        ],
        "steps": [
          "指定每类数据的权威owner",
          "把原件、索引、记忆和临时上下文分层",
          "模拟丢失、落后与恢复"
        ],
        "outputs": [
          "可恢复的数据职责图",
          "明确一致性与删除边界"
        ]
      },
      "citations": [
        {
          "url": "https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html",
          "label": "AWS：事务与派生系统同步",
          "kind": "official-doc"
        },
        {
          "url": "https://github.com/pgvector/pgvector",
          "label": "pgvector：关系库中的向量扩展",
          "kind": "code"
        }
      ],
      "links": [
        {
          "target": "knowledge-provenance-versions",
          "type": "implements",
          "reason": "权威原件与派生索引分层"
        },
        {
          "target": "retrieval-graph-rag",
          "type": "controls",
          "reason": "LLM图边仍是派生物"
        },
        {
          "target": "memory-semantic-facts",
          "type": "controls",
          "reason": "记忆不自动升级为权威事实"
        },
        {
          "target": "checkpoint-recovery",
          "type": "feeds",
          "reason": "恢复状态存权威层"
        },
        {
          "target": "storage-outbox-consistency",
          "type": "requires",
          "reason": "派生检索层需同步合同"
        }
      ]
    },
    {
      "id": "unknown-operation-outcome",
      "title": "结果未知与对账",
      "en": "Unknown Operation Outcome",
      "aliases": [
        "结果未知",
        "Read-back对账"
      ],
      "kind": "concept",
      "parentId": "runtime-tools",
      "order": 50,
      "summary": "工具调用超时后，外部动作可能已发生但尚未确认。",
      "question": "超时后不知道动作是否成功，下一步应做什么？",
      "body": "工具调用超时后，外部动作可能已发生但尚未确认。\n\n结果未知是一种需要独立处理的状态。超时或断网只能说明应用没有拿到确定回应，不能证明目标系统没有执行。对于写操作，把unknown直接改成failed并重试，可能造成重复发送、重复下单或相反方向的补偿。\n\n操作账本先保存意图与稳定业务ID，调用后记录receipt。发生不确定性时，查询目标系统的操作状态、唯一业务标识或最终记录；必要时人工对账。查询也可能延迟可见，因此要明确等待、重查和截止规则，而不是立即认定不存在。平台应向用户说明正在确认效果，避免误导其手工再做一次。\n\n只读操作通常可以在预算内重试，但仍需留意计费、资源消耗和查询时间边界。写操作需要更严格分类：未发送、已发送未确认、已确认成功、已确认失败。只有能证明未执行或具备幂等保障时，才允许自动重新提交。补偿是新的业务动作，可能失败，也不能伪装成真正回滚。\n\n测试可以让目标系统完成工作后故意丢弃响应，再观察Agent是否先read-back。还要测试目标查询暂时空、回执延迟、重复回调和人工已介入等情况。完成标准是业务最终状态与本地记录能够对齐，不是所有Attempt都必须得到即时成功。此状态设计直接决定恢复和取消是否可信。\n\n面向用户的恢复按钮也要基于状态。unknown时不直接提供“再发送”作为默认选择，而应先展示查询结果或需要确认的风险。若用户明确决定再次执行，记录新的授权及其与原操作的关联。这样既不阻止合法工作，也避免界面把不确定性转化成无意识重复。\n\n对账过程也需要deadline和owner，长期unknown不能无人处理。达到查询上限后进入人工队列，保留已知事实和每次查询结果。\n\n**实践重点**：进入unknown并读回业务状态或人工对账；禁止直接标失败重放。\n\n**验证抓手**：模拟响应丢失，检验read-back和人工接管。\n\n**常见误区**：以HTTP断连推断外部操作没发生。\n\n[Temporal：执行状态与外部副作用](https://docs.temporal.io/ai/featured/memory-state-stripe)；[OpenCode：流、工具和取消源码](https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/runner/step.ts#L32-L245)。",
      "blueprint": {
        "inputs": [
          "超时操作身份",
          "已发送参数及批准",
          "目标查询与回执接口"
        ],
        "steps": [
          "标为unknown停止盲重放",
          "读回目标业务状态",
          "等待或人工对账",
          "提交确认结果"
        ],
        "outputs": [
          "确认成功或失败",
          "未决对账项",
          "安全恢复决定"
        ]
      },
      "citations": [
        {
          "url": "https://docs.temporal.io/ai/featured/memory-state-stripe",
          "label": "Temporal：执行状态与外部副作用",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/runner/step.ts#L32-L245",
          "label": "OpenCode：流、工具和取消源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        }
      ],
      "links": [
        {
          "target": "idempotent-side-effects",
          "type": "requires",
          "reason": "本节点的设计需要先明确业务副作用幂等。"
        }
      ]
    },
    {
      "id": "checkpoint-recovery",
      "title": "Checkpoint与恢复",
      "en": "Checkpoint Recovery",
      "aliases": [
        "检查点",
        "故障恢复"
      ],
      "kind": "concept",
      "parentId": "runtime-task-session",
      "order": 60,
      "summary": "保存可继续执行的状态及其版本，支持失败后继续。",
      "question": "保存了状态之后，还要验证哪些恢复边界？",
      "body": "保存可继续执行的状态及其版本，支持失败后继续。\n\nCheckpoint保存的是能够继续执行的状态，而非某段聊天的备份。LangGraph的公开模型包含channel值、版本和各节点已见版本；runner将成功写入、错误、中断和取消分别提交。这使运行时能够知道下一步该执行什么，但不会自动让外部系统中的副作用变成exactly-once。\n\n持久化后端必须与部署匹配。内存saver适合本地实验，进程重启后状态消失；数据库saver则有迁移、连接、清理与增长成本。业务Task、图thread和checkpoint namespace需要明确对应，不能把用户可提交的thread_id当访问凭证。恢复一个状态前，先验证主体仍有权继续。\n\n每个工具边界应记已请求、已提交、已确认或结果未知。模型推理可以在失败后重新调用，但已提交的关键业务决定不能恢复时随意重生。工具成功后checkpoint失败的空隙，应通过稳定操作ID和外部read-back弥合。审批恢复还要检查批准参数、资源版本和有效期。\n\n恢复保证需要用故障注入证明：杀进程、丢回调、重复投递、数据库暂时失联和部署升级。检查成功节点是否不必要重做，未知动作是否进入对账，取消是否阻止新增工作。checkpoint保留和压缩也要有策略；无限保存完整状态会增加延迟与费用。能够“继续聊天”，不能代替这些恢复验收。\n\n部署升级时还需检验旧检查点能否由新代码读取。状态字段改名、工具结果schema变化或节点拆分，都可能破坏恢复。可以保留旧运行版本完成在途任务，或提供显式迁移与回退；不能因为新版本构建成功就删除旧运行镜像。恢复能力本身应作为发布验收对象。\n\n恢复测试应留下外部状态对照和事件边界证据，不能只凭进程重新启动或页面重新打开来宣称通过。\n\n**实践重点**：检查点包含图状态、已提交结果和待执行边界；明确持久化后端。\n\n**验证抓手**：在调用前后、结果保存前后kill worker并核对外部结果。\n\n**常见误区**：有聊天历史就声称可恢复，或恢复时重复不可逆动作。\n\n[LangGraph：Checkpoint模型源码](https://github.com/langchain-ai/langgraph/blob/889a5ff16f8325113093d517dffd5471a943c760/libs/checkpoint/langgraph/checkpoint/base/__init__.py#L93-L123)；[LangGraph：Runner提交源码](https://github.com/langchain-ai/langgraph/blob/889a5ff16f8325113093d517dffd5471a943c760/libs/langgraph/langgraph/pregel/_runner.py#L575-L615)。",
      "blueprint": {
        "inputs": [
          "持久checkpoint",
          "待决工具与审批状态",
          "当前授权和版本"
        ],
        "steps": [
          "验证恢复资格",
          "加载状态及pending writes",
          "核对未知外部效果",
          "从合法边界继续"
        ],
        "outputs": [
          "恢复后的Run",
          "去重和对账结果",
          "故障恢复证据"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/langchain-ai/langgraph/blob/889a5ff16f8325113093d517dffd5471a943c760/libs/checkpoint/langgraph/checkpoint/base/__init__.py#L93-L123",
          "label": "LangGraph：Checkpoint模型源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        },
        {
          "url": "https://github.com/langchain-ai/langgraph/blob/889a5ff16f8325113093d517dffd5471a943c760/libs/langgraph/langgraph/pregel/_runner.py#L575-L615",
          "label": "LangGraph：Runner提交源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        }
      ],
      "links": [
        {
          "target": "event-log",
          "type": "requires",
          "reason": "本节点的设计需要先明确事件日志。"
        },
        {
          "target": "idempotent-side-effects",
          "type": "requires",
          "reason": "本节点的设计需要先明确业务副作用幂等。"
        }
      ]
    },
    {
      "id": "completion-contract",
      "title": "任务完成合同",
      "en": "Completion Contract",
      "aliases": [
        "验收合同",
        "后置条件"
      ],
      "kind": "concept",
      "parentId": "runtime-harness",
      "order": 60,
      "summary": "用可观察后置条件判定业务工作是否完成。",
      "question": "怎样区分模型说完成和业务真正完成？",
      "body": "用可观察后置条件判定业务工作是否完成。\n\n完成合同把“看起来做完”变成可观察、可核验的业务条件。研究任务可能要求每个指标有原件定位和计算过程；教学任务可能要求学生在无提示下解出迁移题；外部执行任务可能要求目标系统出现正确状态。不同任务的完成证据不同，不能用一个语言评分覆盖全部场景。\n\n模型输出完成声明只能触发verification。工具返回HTTP 200可能只说明受理请求；文件存在可能仍为空、损坏或使用了错误资料。Task应保存验收版本和逐项结果，把产物生成、验证通过与真正交付分开。若报告已经生成但客户投递失败，应展示两个状态，不能因为文本写得好就把整个任务标成功。\n\n设计验收时，把确定性条件交给程序：公式复算、文件格式、目标记录、数量和权限；把解释质量交给校准过的judge或专家；把学习保持、投资结果等长期效果交给独立观察。验证器可以共享工具，但不应只是复述主Agent的自评。对于不可自动验证的关键结论，应保留未知和人工复核点。\n\n成功、失败、取消、受阻与部分完成应有不同含义。预算耗尽时输出已完成项和证据缺口，是可解释结束，不能改写成成功。测试故意制造“API受理未落地”“引用存在但语境不支持”“文件生成但内容错版”等反例，并确认系统拒绝提前通过。完成合同越具体，Agent选择工具和停止的行为才越容易评测。\n\n验收不应只验证正例。一个财报值可能存在于真实页面，却属于错误公司或期间；一个法律引用可能真实存在，却已经被后续权威限制；一道题的答案可能正确，却是提示后照抄。将这些“形式通过、业务不成立”的反例加入测试，才能避免完成条件被模型以表面方式满足。\n\n**实践重点**：验收条件由业务定义，模型仅生成完成候选；独立验证通过后提交成功。\n\n**验证抓手**：故意让工具返回受理但未生效，检查Task是否拒绝提前成功。\n\n**常见误区**：用流畅答案、HTTP 200或模型自评替代外部结果。\n\n[Anthropic：长期任务Harness](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)；[Temporal：执行状态与外部副作用](https://docs.temporal.io/ai/featured/memory-state-stripe)。",
      "blueprint": {
        "inputs": [
          "版本化验收规则",
          "候选产物",
          "工具回执与业务状态"
        ],
        "steps": [
          "拆出可程序验证条件",
          "核查语义及证据",
          "读回外部后置状态",
          "提交通过或未通过原因"
        ],
        "outputs": [
          "逐项验证结果",
          "Task最终状态",
          "可解释的缺口或交付证明"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents",
          "label": "Anthropic：长期任务Harness",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://docs.temporal.io/ai/featured/memory-state-stripe",
          "label": "Temporal：执行状态与外部副作用",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": [
        {
          "target": "business-task",
          "type": "requires",
          "reason": "本节点的设计需要先明确业务Task。"
        },
        {
          "target": "tool-contract",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具接口合同。"
        }
      ]
    },
    {
      "id": "knowledge-document-parsing",
      "title": "文档解析与OCR质量",
      "aliases": [
        "OCR",
        "document parsing",
        "layout"
      ],
      "kind": "concept",
      "parentId": "knowledge-ingestion",
      "order": 60,
      "summary": "阅读顺序、页码坐标、OCR置信、解析版本与错误隔离。",
      "question": "为什么文件读到了，Agent仍可能读错？",
      "body": "### 从可读文字到可用结构\n\nPDF能抽取出文字，不代表模型读到了正确顺序。双栏页面可能被交叉拼接，页眉被插入正文，脚注与限定条件分离；扫描件还可能把小数点、负号和英文缩写识别错。这些错误进入检索之后常被误诊为embedding或生成模型不够强。\n\nDocling公开实现提供版面分析、阅读顺序、表格结构、OCR及统一文档表示。可把它作为解析候选，但“支持某种格式”只证明接口覆盖，不证明企业实际资料已经正确处理。原生PDF、扫描PDF、演示文稿、邮件和电子表格应各有代表样本。\n\n### 中间表示必须保留定位\n\n建议输出段落类型、标题层级、页码、坐标框、链接、列表、代码块与附件关系，同时保存原件指纹、解析器版本和OCR配置。原件与解析JSON分别保存，后续更换解析器时可以重建，而无需再次依赖源系统下载或把旧错误当作新事实。\n\n批注、修订、隐藏工作表、备注和邮件引用不能由解析器默认决定是否进入知识库。产品应明确哪些内容属于正式正文，哪些只是建议、历史版本或转述。图像识别生成的描述也要标记为派生内容，保留回看原图的入口。\n\n质量门控应建立在可核验字段上：抽查关键数值、页面阅读顺序、章节连续性及定位正确性；低置信或异常长度的文档进入隔离队列。关键表格不宜仅用一项“平均OCR准确率”验收，因为一个金额的错误可能比整页普通文字的遗漏更严重。\n\n发布前用一组固定困难样本比较解析版本，检查下游检索是否因此变化。能打开文件、解析任务成功、文本不为空和正确恢复文档语义是四个不同结果；只有最后一种才足以支持可靠回答。",
      "blueprint": {
        "inputs": [
          "原始文件与类型",
          "文档样本及正文纳入规则"
        ],
        "steps": [
          "按类型运行解析与OCR",
          "保留结构、坐标和解析版本",
          "用困难样本进行字段与顺序核验"
        ],
        "outputs": [
          "可定位的结构化文档",
          "隔离错误与质量报告"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/docling-project/docling",
          "label": "Docling：结构化文档转换",
          "kind": "code"
        }
      ],
      "links": [
        {
          "target": "knowledge-table-multimodal",
          "type": "feeds",
          "reason": "版面恢复为表格与图像提供结构"
        },
        {
          "target": "retrieval-chunking",
          "type": "feeds",
          "reason": "解析结构决定切块边界"
        }
      ]
    },
    {
      "id": "memory-semantic-facts",
      "title": "事实与用户偏好记忆",
      "aliases": [
        "semantic memory",
        "user preference",
        "事实记忆"
      ],
      "kind": "concept",
      "parentId": "memory-types",
      "order": 60,
      "summary": "semantic fact和明确偏好、实体/属性/来源/范围/验证状态；偏好不授权动作。",
      "question": "哪些对话信息值得变成跨会话可检索事实？",
      "body": "### 保存可定位的事实，而不是无限对话\n\n用户明确表示“邮件以后用中文”，可以成为跨会话偏好；一次任务中出现的金额、猜测或第三方说法，则未必适合长期保存。Semantic memory描述可复用事实与概念，和使用向量寻找相似文本的semantic search不是同一个概念。\n\nLangChain的memory文档将事实、经历和程序区分，提供了有用分类。企业实现还需决定谁能写、作用范围、来源、何时失效以及怎样更正。不能因为某信息被系统记住，就自动把它提升为正式制度或得到授权的动作。\n\n### 每条事实有明确身份\n\n建议保存subject、predicate、value或结构化content、scope、来源事件、验证状态、有效时间与version。事实条目尽量小，使修改一个偏好不必改写整个用户档案。模型自评分与外部验证要分开，0.95的自评分不能解释为95%正确。\n\n明确陈述、可靠业务记录、已验证任务产物和模型推断应有不同信任层级。系统可以保存“用户提出假设X”，却不能把它缩写成“X是真的”。同一模型重复生成的说法也不是多个独立来源，不能通过自我引用形成虚假佐证。\n\n### 作用范围决定能否复用\n\n用户偏好通常属于个人，团队约定属于组织，客户事实属于事项。读取时先限定范围、当前授权和时间，再考虑相关性。关于投资的风险偏好与下单授权、关于邮件的写作偏好与发送许可必须由不同对象表达。\n\n验收准备显式偏好、临时条件、转述、假设、敏感信息和矛盾更新的样本，检查写入precision与未来使用是否合适。成功不是记住最多内容，而是下一次任务能使用正确、允许且仍有效的信息，并在用户纠正时停止使用旧值。",
      "blueprint": {
        "inputs": [
          "明确陈述或可信业务记录",
          "主体、scope与来源"
        ],
        "steps": [
          "抽取小粒度事实候选",
          "判定信任、有效时间与用途",
          "准入后按范围检索并支持更正"
        ],
        "outputs": [
          "带验证与来源的事实项",
          "可撤回的用户偏好"
        ]
      },
      "citations": [
        {
          "url": "https://docs.langchain.com/oss/python/concepts/memory",
          "label": "LangChain：Memory overview",
          "kind": "official-doc"
        },
        {
          "url": "https://help.getzep.com/v4/memory-security",
          "label": "Zep v4：Memory security",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "knowledge-provenance-versions",
          "type": "requires",
          "reason": "事实项关联来源"
        },
        {
          "target": "memory-write-admission",
          "type": "requires",
          "reason": "抽取结果先候选后准入"
        }
      ]
    },
    {
      "id": "retrieval",
      "title": "检索与证据",
      "aliases": [
        "retrieval",
        "RAG",
        "搜索精度"
      ],
      "kind": "domain",
      "parentId": null,
      "order": 60,
      "summary": "查询、表示、候选召回、重排、证据组装和路由。",
      "question": "如何从授权资料中找齐并选准当前任务证据？",
      "body": "检索服务把问题转成一组当前可访问、与任务相关且能够引用的证据。召回、重排和证据组装分别决定找不找得到、排不排得准、模型最终看见什么，三层需要独立诊断。\n\n一个可观察基线是保留原query，按需补充结构条件，并行词法与dense召回，去重融合，有限候选重排，再补齐父段和表头。简单问题可以走确定性管线；需要继续搜索时，由明确证据缺口驱动并设置轮次、时间和成本预算。\n\n本分支同时讨论切块、上下文增强、过滤ANN、GraphRAG、结构化查询、长上下文和embedding迁移。选择策略的依据是任务所需证据，而不是采用组件的数量。检索质量和答案正确性分开评分，近似索引召回与语义相关性也不能互换。",
      "blueprint": {
        "inputs": [
          "问题、身份与约束",
          "已发布知识及索引"
        ],
        "steps": [
          "多路召回并融合",
          "重排并补齐证据",
          "检查覆盖、版本与授权"
        ],
        "outputs": [
          "可引用证据包",
          "可诊断的检索轨迹"
        ]
      },
      "citations": [
        {
          "url": "https://docs.vespa.ai/en/learn/tutorials/hybrid-search",
          "label": "Vespa：混合检索",
          "kind": "official-doc"
        },
        {
          "url": "https://www.anthropic.com/engineering/contextual-retrieval",
          "label": "Anthropic：上下文检索",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "retrieval-query-planning",
      "title": "查询理解与改写",
      "aliases": [
        "query rewriting",
        "query decomposition"
      ],
      "kind": "concept",
      "parentId": "retrieval-pipeline",
      "order": 60,
      "summary": "保留原query、抽取ID/实体/日期/地区、受控扩展、记录改写与证据缺口。",
      "question": "什么时候需要改写问题，什么时候应保留精确名称和编号？",
      "body": "### 改写的目标是补齐检索条件\n\n用户问“新版本报销到底改了什么”时，检索需要识别资料域、版本、地区和比较对象；用户问一个精确错误码时，最重要的可能是保留原字符串。查询处理不应默认把所有问题交给模型自由改写，因为改写也可能删除编号、否定词和日期，扩大本应受限的搜索范围。\n\n建议始终保存原query，在旁路生成结构化条件与可选改写：实体、精确ID、语言、as-of、资料类型和未明确的约束。授权条件由服务端加入，不能由改写模型推断。Vespa的查询与排名分离机制说明召回表达与后续打分可以独立设计，原始问题也应保留供最终重排。\n\n### 一次改写不等于一次事实发现\n\n扩展同义词可改善术语差异，跨语言变体可帮助寻找原始英文资料，但生成的新词不是已经存在的事实。使用假设性描述构造查询时，应标记其搜索用途，并保留原query并行召回，避免模型的先验错误把候选集带偏。\n\n对多部分问题，可以拆成具有明确证据需求的子query，如某一地区旧版上限、新版上限和生效日期。是否继续搜索应由尚未解决的证据缺口决定，而不是只因Agent仍有剩余轮次。每次扩展要消耗独立的时间与费用预算。\n\n### 评价信息保持与额外收益\n\n固定一组含产品代号、日期、否定条件和中英混写的问题，比较原query与改写query的必需证据召回。记录改写删除了什么、增加了什么、是否改变问题含义，以及多出的模型调用带来多少真正新增成功。\n\n当原query已经足以定位资料时，跳过改写通常更简单。若问题缺少决定性条件，可以先给出明确范围的检索结果或请求补充；不能默默选择一个地区，再把结果写成全企业通用结论。",
      "blueprint": {
        "inputs": [
          "原始问题",
          "服务端身份与资料约束"
        ],
        "steps": [
          "提取精确字段并保留原文",
          "按证据缺口生成有限变体",
          "比较新增召回与语义偏移"
        ],
        "outputs": [
          "可追踪query集合",
          "明确资料域和未解决条件"
        ]
      },
      "citations": [
        {
          "url": "https://docs.vespa.ai/en/learn/tutorials/hybrid-search",
          "label": "Vespa：混合检索教程",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "retrieval-lexical-bm25",
          "type": "feeds",
          "reason": "精确词保留给词法检索"
        },
        {
          "target": "retrieval-dense-embeddings",
          "type": "feeds",
          "reason": "语义表达供向量检索"
        }
      ]
    },
    {
      "id": "retry-policy",
      "title": "错误分类与重试",
      "en": "Retry Policy",
      "aliases": [
        "错误恢复",
        "指数退避"
      ],
      "kind": "concept",
      "parentId": "runtime-tools",
      "order": 60,
      "summary": "根据失败类型、重放安全性和剩余预算决定是否重试。",
      "question": "哪些错误可以重试，怎样控制重放和总预算？",
      "body": "根据失败类型、重放安全性和剩余预算决定是否重试。\n\n重试策略要回答三个问题：这类错误是否可能自行恢复，重复执行是否安全，剩余时间和费用是否值得。429、短暂断流、无效schema、权限拒绝和数据矛盾，需要不同处理；统一捕获异常再调用一次，往往掩盖根因并放大副作用。\n\n短时服务错误可遵循Retry-After或供应商提示，使用指数退避和jitter，但仍受端到端deadline限制。参数错误可返回结构化反馈让模型限次修正；权限拒绝不能通过改写参数或更换子Agent绕过；数据缺失应保留未知或找合法替代来源。写工具超时先进入unknown并查询回执。\n\n流中断尤其需要判断输出已经到哪一步。OpenCode研发源码区分是否已产生输出以及恢复方式；Agents SDK模型接口也允许provider返回重试建议。已经发生本地工具调用后，完整重放请求可能不再安全。恢复应复用已确认结果，而不是让新请求重新决定是否执行同一动作。\n\n记录每次Attempt、失败类别、等待时间与重试理由，设置单操作上限和任务总预算。测试逐类注入故障，并观察是否出现多层重试相乘：SDK、工具网关和外层workflow都重试三次，可能形成九次甚至更多外部请求。只有一个明确的权威控制业务重放，其余层处理受限传输恢复。\n\n还要区分技术重试与业务重新执行。前者保持原参数和操作身份，后者可能改变范围、来源和验收，需要新合同或版本。模型修正一个无效字段后，如果字段改变了已批准动作，就不能沿用旧批准。把这些情况统一叫retry，会让恢复逻辑绕过本来正确的审批边界。\n\n重试指标应同时报告最终成功率、额外调用和严重重复效果；仅提高HTTP成功率，可能让业务可靠性更差。\n\n**实践重点**：429退避与jitter；schema限次修复；拒绝授权不绕过；写超时先对账。\n\n**验证抓手**：逐类注入429、断流、错误参数与权限拒绝。\n\n**常见误区**：所有异常统一再试一次，放大费用和副作用。\n\n[Agents SDK：Model接口和call ID约束](https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/models/interface.py#L37-L80)；[OpenCode：流、工具和取消源码](https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/runner/step.ts#L32-L245)。",
      "blueprint": {
        "inputs": [
          "错误分类及provider建议",
          "操作重放安全性",
          "剩余deadline和费用"
        ],
        "steps": [
          "判定可恢复与可重放",
          "选择退避或限次修复",
          "查询未知写效果",
          "记录Attempt和停止原因"
        ],
        "outputs": [
          "重试或停止决定",
          "可归因错误轨迹",
          "受控费用和副作用"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/models/interface.py#L37-L80",
          "label": "Agents SDK：Model接口和call ID约束",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        },
        {
          "url": "https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/runner/step.ts#L32-L245",
          "label": "OpenCode：流、工具和取消源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        }
      ],
      "links": [
        {
          "target": "unknown-operation-outcome",
          "type": "requires",
          "reason": "本节点的设计需要先明确结果未知与对账。"
        },
        {
          "target": "deadline-propagation",
          "type": "requires",
          "reason": "本节点的设计需要先明确Deadline与剩余预算。"
        }
      ]
    },
    {
      "id": "storage-postgres-pgvector",
      "title": "PostgreSQL与pgvector",
      "aliases": [
        "Postgres",
        "pgvector",
        "关系向量库"
      ],
      "kind": "product",
      "parentId": "storage-engines",
      "order": 60,
      "summary": "事务/RLS/关联/全文/向量组合、OLTP资源争用、filtered recall与运维边界。",
      "question": "什么情况下一个托管关系库就足以承载初期Agent数据层？",
      "body": "### 适合先减少系统数量\n\n已有PostgreSQL能力的团队，可以在托管关系库中保存任务、权限、来源版本、记忆事实与向量，使用关联和事务维护这些对象。pgvector提供向量相似搜索及近似索引，因此初期不必仅因需要embedding就额外引入一个服务。\n\n收益主要是数据合同与运维复用，而不是“所有规模都比专用向量库更快”。业务OLTP、全文查询、向量扫描和HNSW构建会争用资源；大规模更新、VACUUM、索引膨胀、备份和恢复都应进入容量与延迟预算。\n\n### 过滤和执行计划要实测\n\npgvector官方说明近似扫描后过滤可能导致结果不足，iterative scans可以继续扫描直到达到条件或上限。共享索引的tenant分布还可能互相影响召回和速度。需要检查实际执行计划，比较不同授权子集下的exact和ANN，不应只运行无过滤demo。\n\nRLS可成为防御层，但必须用真实应用角色验证；表owner、superuser与BYPASSRLS具有特殊行为，连接池复用也不能残留上一用户的session身份。中文全文配置需要单独验证术语与编号，并非默认配置即可满足所有企业语言。\n\n### 何时保留，何时拆分\n\n若现有库在目标并发与更新负载下满足filtered recall、p95和恢复要求，继续共库通常比增加服务更易维护。若检索资源开始拖累业务事务，或者需要独立向量伸缩、多向量和专用布局，可以把索引迁出，保留权威元数据与事件合同。\n\n验收应同时压入业务写入、索引重建和真实过滤query，观察任务状态查询是否受影响。向量数不是唯一阈值；维度、冷热比例、候选预算、tenant倾斜和维护窗口才决定这个选择是否可持续。",
      "blueprint": {
        "inputs": [
          "关系数据与授权模型",
          "代表性向量和过滤负载"
        ],
        "steps": [
          "建立pgvector与全文基线",
          "检查RLS及实际执行计划",
          "在混合负载下验证资源边界"
        ],
        "outputs": [
          "可共库的初期数据层",
          "拆分检索服务的实测触发条件"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/pgvector/pgvector",
          "label": "pgvector官方实现",
          "kind": "code"
        },
        {
          "url": "https://www.postgresql.org/docs/17/ddl-rowsecurity.html",
          "label": "PostgreSQL：Row Security Policies",
          "kind": "official-doc"
        },
        {
          "url": "https://github.com/pgvector/pgvector/blob/master/LICENSE",
          "label": "pgvector LICENSE",
          "kind": "code",
          "note": "许可范围按实际使用的版本、路径及分发包再次核对。"
        }
      ],
      "links": [
        {
          "target": "retrieval-filtered-ann",
          "type": "implements",
          "reason": "pgvector迭代扫描与分区"
        },
        {
          "target": "retrieval-structured-queries",
          "type": "implements",
          "reason": "关系查询与向量可共享权威库"
        },
        {
          "target": "storage-authority-derived",
          "type": "implements",
          "reason": "在一个权威状态库内组合检索"
        },
        {
          "target": "retrieval-filtered-ann",
          "type": "requires",
          "reason": "过滤后的召回需单独测"
        },
        {
          "target": "storage-managed-procurement",
          "type": "complements",
          "reason": "优先评估托管服务"
        },
        {
          "target": "memory-concurrent-mutation",
          "type": "implements",
          "reason": "关系事务实现事实项更新"
        }
      ],
      "productRoute": {
        "vendor": "PostgreSQL社区 / pgvector",
        "category": "关系库与向量扩展",
        "execution": "SQL事务与向量查询",
        "orchestration": "由应用或Agent runtime编排",
        "context": "全文、关系条件与向量候选",
        "persistence": "关系状态可权威保存",
        "modelBoundary": "embedding revision与查询索引匹配",
        "deployment": "优先托管PostgreSQL",
        "license": "PostgreSQL License；云服务条款独立",
        "availability": "pgvector公开项目；扩展版本和区域按托管商确认",
        "strengths": "事务、关联、权限和运维可复用",
        "limits": "OLTP争用、过滤召回、维护与恢复需实测"
      }
    },
    {
      "id": "knowledge-table-multimodal",
      "title": "表格与多模态证据",
      "aliases": [
        "table extraction",
        "multimodal evidence"
      ],
      "kind": "concept",
      "parentId": "knowledge-ingestion",
      "order": 70,
      "summary": "表头、单位、脚注、合并单元格、续表、原页图像及双通道证据。",
      "question": "如何避免250这样的数字离开表头后失去意义？",
      "body": "### 一个数字需要完整的语义坐标\n\n检索到“250”没有实际用途，除非同时知道它属于哪一行、哪一列、什么币种、哪个时期及什么适用条件。表格抽取的核心不是得到更多文字，而是保留行列关系、表名、单位、脚注、合并单元格和跨页延续。财报、费率表和教育评分rubric尤其依赖这些关系。\n\nDocling的统一表示保留表格结构与版面信息，可用于构建表格证据；对于复杂扫描件，仍应把结构化结果与原页图像关联。建议把文本/单元格结构用于召回，把原页或局部截图用于定点核验，而不是让模型凭失真的Markdown补齐布局。\n\n### 切块和读取采用不同粒度\n\n大表可以按有意义的行组拆分，但每组重复携带列名、表标题与单位；分层表头要展开成明确字段。跨页重复表头不可当数据行，续表需要连接到前页定义。若脚注改变数字含义，脚注应与相关行一起组装成最终证据。\n\n并非所有图都适合直接向量化。流程图可能需要节点关系，趋势图需要坐标轴与系列，截图包含的按钮文字可能还需要视觉定位。先确认用户问题依赖什么视觉信息，再选择OCR、结构抽取或多模态检索，避免为简单文字图增加昂贵模型调用。\n\n### 用数值问题验收\n\n建立包含原始页面、标准单元格、单位和脚注的样本集，分别测值、行列定位与上下文恢复。错误应能回溯到解析、切块、检索或模型读取某一层。最终答案中的计算交给确定性工具，模型只负责解释口径与证据。\n\n一个有效的反例是两张标题相似但币种不同的表：系统既要找对目标表，也要拒绝把另一张表的数值拼入计算。验证页面可读还不够，应检查引用指向准确的原页和有效版本。",
      "blueprint": {
        "inputs": [
          "表格或图像原页",
          "标题、表头、单位与脚注"
        ],
        "steps": [
          "恢复单元格与视觉结构",
          "按行组建可检索证据并保留原页",
          "对关键数值定点核验"
        ],
        "outputs": [
          "带语义坐标的证据",
          "可回看原页的数值引用"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/docling-project/docling",
          "label": "Docling：结构化文档转换",
          "kind": "code"
        }
      ],
      "links": [
        {
          "target": "knowledge-document-parsing",
          "type": "requires",
          "reason": "表格依赖布局结构"
        },
        {
          "target": "retrieval-evidence-assembly",
          "type": "feeds",
          "reason": "证据需补齐表头与脚注"
        },
        {
          "target": "knowledge-finance-as-of",
          "type": "feeds",
          "reason": "财报数字保留口径与出处"
        }
      ]
    },
    {
      "id": "memory-episodic-experience",
      "title": "任务经历与失败经验",
      "aliases": [
        "episodic memory",
        "experience replay",
        "任务经历"
      ],
      "kind": "concept",
      "parentId": "memory-types",
      "order": 70,
      "summary": "episode、成功/失败轨迹、环境版本、验证证据与可检索经验。",
      "question": "如何记住过去发生了什么而不过度总结成通用规律？",
      "body": "### 记录经历，不急着总结规律\n\n某次任务在一个API版本下失败、某个网页控件需要特殊操作、一次财报比较如何核对口径，都可以成为episode。它记录发生了什么、条件是什么、怎样验证以及结果如何，帮助后续任务避免重复探索。它不等同于“以后永远这样做”的规则。\n\nLangChain把episodic memory与事实、程序记忆区分，常通过相关历史例子辅助当前行为。应用可以保存精简经历并指向原始trace，避免每次检索整段聊天；但摘要中的关键判断必须能回到工具结果与验证证据。\n\n### 环境和结果必须完整\n\n建议episode包含任务类型、输入条件、工具/模型/环境版本、行动摘要、成功判据、失败类别、证据和局限。将“API返回200”“文档生成”“业务状态读回”和“人类确认”分别记录，不能统称成功。人类补救的部分也要保留，避免Agent错误学习自身已具备能力。\n\n失败经历有时比成功例更有用，但需知道是否已被新版本修复。一次偶然超时不应被记成永远不可调用某工具，用户临时例外也不应成为通用流程。经历检索应考虑环境兼容、时间与反例，而非只看语义相似度。\n\n### 从复用效果判断价值\n\n可比较无经历、随机经历和相关经历三组，观察是否减少重复失败、工具次数和人工修正。若检索到过多旧失败，让模型过度保守或绕过正确新接口，也属于记忆退化。需要跟踪某个episode被使用后造成的结果。\n\n程序化推广应进入独立能力准入流程：多个经过验证的经历可以支持候选skill，单次“看起来成功”的轨迹不能自动修改全局提示词。验收要同时覆盖成功与失败归因、环境变化和错误经验撤回，证明系统积累的是可用证据而不是更多故事。",
      "blueprint": {
        "inputs": [
          "任务轨迹与外部验证",
          "模型、工具和环境版本"
        ],
        "steps": [
          "提取条件、行动、结果与局限",
          "保留原trace引用",
          "按适用性检索并观察复用效果"
        ],
        "outputs": [
          "可复核经验片段",
          "带边界的失败与成功案例"
        ]
      },
      "citations": [
        {
          "url": "https://docs.langchain.com/oss/python/concepts/memory",
          "label": "LangChain：Memory overview",
          "kind": "official-doc"
        },
        {
          "url": "https://help.getzep.com/v4/agent-skills/learning-and-admission",
          "label": "Zep：由验证轨迹形成能力候选",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "memory-procedural-skills",
          "type": "feeds",
          "reason": "多次验证经验可提出程序候选"
        },
        {
          "target": "observability-traces",
          "type": "requires",
          "reason": "可追溯经历需要运行事件与产物证据；摘要不替代原始事实。"
        }
      ]
    },
    {
      "id": "no-progress-detection",
      "title": "无进展检测",
      "en": "No-progress Detection",
      "aliases": [
        "循环检测",
        "停滞检测"
      ],
      "kind": "concept",
      "parentId": "runtime-harness",
      "order": 70,
      "summary": "识别重复行动且未减少未决验收项的循环。",
      "question": "怎样识别无效循环，又不误停有效长任务？",
      "body": "识别重复行动且未减少未决验收项的循环。\n\nAgent会重复搜索、反复修改同一段文字，也可能在缺少授权或数据时持续尝试。无进展检测关注目标状态是否改善，而非简单计数。两次相同检索可能是验证需要，十次不同查询也可能没有新增证据；单纯限制轮数无法完整识别这些情况。\n\n建议同时观察工具参数、证据增量、未决验收项、候选产物变化与预算。若连续若干步都没有新来源、没有减少关键缺口，也没有改变可验证状态，就应要求改策略。阈值按任务类型实验，不能把固定三步或五步当通用标准。长时间计算也可能有进度，应由工具报告阶段状态，而不是被误判成模型停滞。\n\n恢复动作应有顺序：先确认错误是资料不足、工具失效、规划错误还是模型能力不足；再尝试替代来源、缩小问题、调整工具或切换获准模型。升级模型要消耗剩余预算，也要满足数据和能力合同。权限拒绝或无法得到关键事实，不属于可通过更多推理消除的障碍。\n\n达到停止条件时，保存当前产物、已验证项、缺失证据及继续所需输入。不要把无进展状态隐去，继续展示泛化的“正在努力”。测试集应包含重复网页、空结果、相互循环的工具提示和真正不可解任务，检查停止是否及时、解释是否准确，以及误停是否影响本来可完成的长任务。\n\n可把界面进度从“已执行多少步”改为“已完成多少验收项、还缺什么证据”。后者允许用户判断继续投入是否有价值。无进展报警也要带解释：是没有新增资料、外部工具持续不可用，还是计划反复变化。没有这些区分，系统可能错误地把资料权限问题归因给模型不够聪明。\n\n**实践重点**：跟踪相同调用、证据增量、未决项与候选变化；受预算约束地换策略。\n\n**验证抓手**：用重复搜索与不可解任务测停止、降级与解释。\n\n**常见误区**：无限换模型重试，或仅靠步数把有效长任务误杀。\n\n[Anthropic：长期任务Harness](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)；[Codex：turn与step循环源码](https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/turn.rs#L454-L518)。",
      "blueprint": {
        "inputs": [
          "步骤轨迹",
          "证据与验收项变化",
          "剩余预算"
        ],
        "steps": [
          "识别重复与有效增量",
          "分类停滞根因",
          "限次改变策略",
          "停止并保存缺口"
        ],
        "outputs": [
          "进展信号",
          "策略切换记录",
          "受阻或部分完成结果"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents",
          "label": "Anthropic：长期任务Harness",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://github.com/openai/codex/blob/1ef30bcbe784f1006548adc1542985be32b05109/codex-rs/core/src/session/turn.rs#L454-L518",
          "label": "Codex：turn与step循环源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        }
      ],
      "links": [
        {
          "target": "completion-contract",
          "type": "requires",
          "reason": "本节点的设计需要先明确任务完成合同。"
        },
        {
          "target": "retry-policy",
          "type": "requires",
          "reason": "本节点的设计需要先明确错误分类与重试。"
        }
      ]
    },
    {
      "id": "programmatic-tool-calling",
      "title": "程序化工具调用",
      "en": "Programmatic Tool Calling",
      "aliases": [
        "PTC",
        "代码编排工具"
      ],
      "kind": "concept",
      "parentId": "runtime-tools",
      "order": 70,
      "summary": "用受限代码组合多次工具调用、过滤和聚合数据。",
      "question": "怎样用代码减少工具往返，同时保留每次动作控制？",
      "body": "用受限代码组合多次工具调用、过滤和聚合数据。\n\n程序化工具调用让模型编写受限代码，组合多次查询、过滤与计算，再把必要结果返回上下文。它适合大量细碎调用和数据聚合，可以减少模型往返，但其价值应以真实任务的正确率、延迟和成本衡量，不直接套用厂商演示的节省比例。\n\nAnthropic公开advanced tool use与MCP代码执行文章展示了这条路线。关键变化是部分控制流从自然语言循环进入程序，而非所有步骤都由模型逐条决定。企业可在代码里并行取数、做确定性计算、只输出摘要和证据指针，降低大段工具结果占用窗口。\n\n代码不应获得比直接工具更大的权限。外部调用仍经过网关，逐操作验证scope、批准、幂等和预算；不能把一百次业务写入藏进一个execute_code调用后失去审计。依赖安装、文件、网络、CPU、内存和输出都要限制，生产凭证不直接放进可生成代码的环境。\n\n返回的汇总也要可复算。保留输入数据版本、公式、过滤条件、操作ID和原始产物引用；一次计算成功不证明来源授权或数据口径正确。测试同一任务的逐工具循环与程序调用版本，比较轮次、错误传播、取消和部分失败处理。如果批量执行中第七十个动作失败，系统必须知道前六十九个是否生效，而不是只收到一条程序异常。\n\n对研究型批量计算，可先取只读快照并将代码限制为纯计算，显著缩小副作用风险。需要写入的批任务则应为每个动作返回独立receipt，并采用批次清单记录完成范围。一次脚本退出码不能替代所有子操作的业务成功；部分成功应可以明确导出、继续或对账。\n\n审阅代码时重点看外部效果、资源范围和错误分支，语法编译通过并不足以证明执行安全或结果正确。\n\n**实践重点**：代码仍经授权网关；逐操作审计；限制CPU、网络、包与输出。\n\n**验证抓手**：比较同任务轮次与耗时，并验证每次外部动作可追踪。\n\n**常见误区**：减少模型往返后失去权限和幂等边界。\n\n[Anthropic：Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp)；[Anthropic：Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use)。",
      "blueprint": {
        "inputs": [
          "获准工具和数据接口",
          "受限执行环境",
          "聚合目标与预算"
        ],
        "steps": [
          "生成可检查程序",
          "在沙箱内组合调用",
          "逐操作经过网关",
          "导出摘要和可复算产物"
        ],
        "outputs": [
          "聚合结果",
          "逐操作回执",
          "轮次及成本变化"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/code-execution-with-mcp",
          "label": "Anthropic：Code execution with MCP",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://www.anthropic.com/engineering/advanced-tool-use",
          "label": "Anthropic：Advanced tool use",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": [
        {
          "target": "tool-contract",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具接口合同。"
        },
        {
          "target": "sandbox-lifecycle",
          "type": "requires",
          "reason": "本节点的设计需要先明确沙箱生命周期。"
        }
      ]
    },
    {
      "id": "retrieval-lexical-bm25",
      "title": "词法检索与BM25",
      "aliases": [
        "BM25",
        "inverted index",
        "lexical search"
      ],
      "kind": "concept",
      "parentId": "retrieval-pipeline",
      "order": 70,
      "summary": "倒排索引、中文分析器、精确字段、词法相关性和BM25统计作用域。",
      "question": "为什么错误码、合同号和人名仍需要关键词搜索？",
      "body": "### 精确词不是过时的信号\n\n合同号、错误码、人名、证券代号和罕见专业词，通常比一段宽泛的语义描述更能定位正确材料。词法检索通过倒排索引找到出现这些词的文档，BM25等评分再利用词频、文档长度和词的区分度排序。向量表示未必能保留所有字符级差别，因此不能把词法路线简单删除。\n\nVespa的混合检索教程明确区分词法召回与embedding召回，并演示不同候选组合。借鉴这一结构时，应给标题、正文、精确ID和别名不同字段，而不是把整份文档及所有元数据拼成一条字符串，再依赖统一分词器处理。\n\n### 中文与编号需要单独测试\n\n中文分词、英文缩写、连字符、大小写、全半角和版本号会影响词项。建议对关键ID保留未经分词的精确字段，对正文使用适合语言的分析配置；对相同实体的正式名、简称与英文名建立受控别名。自动扩展出的同义词应可回溯和撤回。\n\nBM25分数依赖索引统计，不是答案正确的概率。跨字段、跨资料域、跨shard或跨tenant时，分数分布也可能不同。Qdrant当前多租户文档特别说明稀疏IDF统计默认作用域可能不等于租户过滤范围，提示检索隔离不只有返回内容隔离。\n\n### 用失败样本决定组合方式\n\n词法基线应包含精确编号、同名实体和近似术语的对抗案例，也包含用户使用自然说法而文档使用正式术语的案例。后者暴露词法局限，适合由dense路线补充，而非无限扩张同义词表。\n\n验收时检查相关证据是否进入候选集、是否被错误分词以及候选是否来自当前授权域。与向量组合时优先比较排名融合；不要直接相加尺度不同的分数，再把某个固定权重称为普遍最佳配置。",
      "blueprint": {
        "inputs": [
          "问题中的词项与精确ID",
          "文本字段及语言分析配置"
        ],
        "steps": [
          "按字段分词或精确匹配",
          "计算词法候选与排名",
          "保留词项命中诊断"
        ],
        "outputs": [
          "词法候选集合",
          "字段与词项匹配证据"
        ]
      },
      "citations": [
        {
          "url": "https://docs.vespa.ai/en/learn/tutorials/hybrid-search",
          "label": "Vespa：混合检索教程",
          "kind": "official-doc"
        },
        {
          "url": "https://qdrant.tech/documentation/manage-data/multitenancy/",
          "label": "Qdrant：多租户与IDF统计",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "retrieval-hybrid-fusion",
          "type": "feeds",
          "reason": "词法结果参与混合召回"
        },
        {
          "target": "knowledge-finance-as-of",
          "type": "feeds",
          "reason": "金融代号与实体匹配需要精确字段"
        }
      ]
    },
    {
      "id": "storage",
      "title": "存储与数据库",
      "aliases": [
        "storage",
        "database",
        "vector database"
      ],
      "kind": "domain",
      "parentId": null,
      "order": 70,
      "summary": "数据角色分工、检索引擎选型、跨库一致性、容量和云采购。",
      "question": "系统真相、原件与派生索引分别存哪里？",
      "body": "数据层先回答谁拥有真相、谁保存原件、谁只是派生索引，再决定使用哪些数据库。Task状态、授权和来源版本需要可靠事务，长文件需要稳定对象引用，搜索需要适合词法、向量与过滤的索引；这些角色可以共库，也可以随着负载拆分。\n\n云优先的起点是托管关系库、对象存储与一个检索路线。选型不采用“达到某个向量数就必须迁移”的单阈值，而是比较实际维度、过滤分布、更新率、并发、冷热和恢复目标。引擎能力、供应商自报性能和企业实测分别记录。\n\n本分支给出各产品的适用与维护边界，也解释outbox、一致性、容量和托管采购。检索算法原理与记忆语义在相邻分支维护，避免每个产品页面重复一份RAG教程。",
      "blueprint": {
        "inputs": [
          "数据职责与业务合同",
          "负载、预算和恢复目标"
        ],
        "steps": [
          "确定权威与派生层",
          "比较引擎和托管路线",
          "验证一致性、容量和恢复"
        ],
        "outputs": [
          "可维护的数据架构",
          "具备证据的选型决策"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/pgvector/pgvector",
          "label": "pgvector：共库路线",
          "kind": "code"
        },
        {
          "url": "https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html",
          "label": "AWS：跨系统一致性",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "storage-qdrant",
      "title": "Qdrant向量检索",
      "aliases": [
        "Qdrant Cloud",
        "payload index"
      ],
      "kind": "product",
      "parentId": "storage-engines",
      "order": 70,
      "summary": "payload索引、多租户、dense+sparse、多向量、量化与服务/client版本。",
      "question": "什么时候值得把向量搜索独立成一个服务？",
      "body": "### 独立向量服务的价值\n\nQdrant适合需要独立扩展向量读写、payload过滤、dense与sparse组合或多向量能力的团队。将它作为检索派生层时，业务任务、权限和来源版本仍可由关系库维护；这使检索资源独立，也增加跨库同步、删除传播与重建责任。\n\n官方多租户文档提供payload分区、自定义sharding与tiered multitenancy，选择取决于小租户数量、热租户和隔离需求。不能简单地为每个用户创建collection，也不能因查询带tenant字段就认为存储布局、统计和性能已经完全隔离。\n\n### 过滤索引与量化有独立合同\n\n对真实过滤字段建立payload索引，并测试严格过滤后的召回。稀疏检索的IDF作用域需要明确，资料内容不泄露不代表排名统计完全隔离。量化可以降低内存压力，但原向量保留、rescore和磁盘访问会影响整体存储与尾延迟。\n\n截至2026-10-15读取的官方文档说明1.19起以memory配置取代已废弃的on_disk与always_ram参数。这提醒实现时应固定server/client版本并核对配置，不能把旧文章中的参数和性能结论直接套到新服务。\n\n### 把跨库失败做成常规测试\n\n一次文档更新应记录期望generation、实际向量版本和消费进度；删除先在权威层禁用，再异步清理Qdrant。查询必须使用与文档相同的embedding revision，结果还要能fetch回当前可访问原件。\n\n验收包括热租户、冷查询、payload漏索引、索引重建和服务限流，报告filtered recall与负载下p95。Qdrant Cloud可以减少自运维负担，但是否符合地域、保留、备份与导出合同仍需按实际套餐确认，不能由开源功能表代替采购核验。",
      "blueprint": {
        "inputs": [
          "文档向量与payload schema",
          "租户分布及过滤查询"
        ],
        "steps": [
          "设计payload/tenant索引",
          "配置表示、量化和查询预算",
          "验证同步、隔离与重建"
        ],
        "outputs": [
          "可独立伸缩的检索层",
          "payload与版本兼容合同"
        ]
      },
      "citations": [
        {
          "url": "https://qdrant.tech/documentation/manage-data/multitenancy/",
          "label": "Qdrant：多租户",
          "kind": "official-doc"
        },
        {
          "url": "https://qdrant.tech/documentation/search-tuning/when-your-collection-outgrows-ram/",
          "label": "Qdrant：内存布局与量化",
          "kind": "official-doc"
        },
        {
          "url": "https://github.com/qdrant/qdrant/blob/master/LICENSE",
          "label": "Qdrant LICENSE",
          "kind": "code",
          "note": "许可范围按实际使用的版本、路径及分发包再次核对。"
        }
      ],
      "links": [
        {
          "target": "retrieval-filtered-ann",
          "type": "implements",
          "reason": "payload索引与tenant布局"
        },
        {
          "target": "storage-outbox-consistency",
          "type": "requires",
          "reason": "独立服务产生跨库一致性边界"
        },
        {
          "target": "storage-managed-procurement",
          "type": "complements",
          "reason": "云优先选择托管形态"
        }
      ],
      "productRoute": {
        "vendor": "Qdrant",
        "category": "独立向量检索服务",
        "execution": "向量与payload检索",
        "orchestration": "由应用维护跨库同步",
        "context": "dense/sparse、多向量与过滤",
        "persistence": "检索派生层；权威元数据另存",
        "modelBoundary": "表示维度、距离和revision显式固定",
        "deployment": "可采用Qdrant Cloud",
        "license": "核心Apache-2.0；托管合同独立",
        "availability": "官方公开项目；Cloud区域和套餐采购时核查",
        "strengths": "独立伸缩与payload索引",
        "limits": "同步、IDF作用域和量化尾延迟需验证"
      }
    },
    {
      "id": "task-scheduler",
      "title": "任务调度",
      "en": "Task Scheduling",
      "aliases": [
        "任务队列",
        "持久调度"
      ],
      "kind": "concept",
      "parentId": "runtime-task-session",
      "order": 70,
      "summary": "将Task分派给有预算、能力与配额的执行资源。",
      "question": "怎样安排任务、等待和资源，而不引入多重重试？",
      "body": "将Task分派给有预算、能力与配额的执行资源。\n\n调度器决定工作何时运行、由谁运行，以及等待和恢复如何发生。它不负责证明模型结论正确。短小、只读且便宜重做的任务可使用任务表与队列；需要等待人工数天、跨部署恢复或协调昂贵副作用时，才比较持久执行引擎和框架托管服务。选择依据是任务合同，而非架构图的规模。\n\n队列往往至少一次投递，同一个Run可能被多个worker看到。领任务要原子更新租约和版本，重复消息按事件或业务操作身份去重。worker崩溃后的重新分配要读取已提交状态，不能从头重做全部外部动作。人工等待应释放计算资源，保留可恢复状态，而不是让进程一直占着连接。\n\n交互问答、后台研究和批量知识接入应有优先级与配额。调度按租户公平，热点用户不能无限占用模型并发。deadline、模型配额、sandbox容量和工具依赖共同决定可接入的工作量。只增加worker数量可能把瓶颈转成429风暴，降低所有任务的完成率。\n\n组合框架时，一项操作只保留一个重试与恢复权威。外层工作流可以管理等待和业务重试，内层Agent负责局部探索，但要明确已提交模型结果和工具回执如何记录。测试至少覆盖重复投递、worker宕机、长时间审批、取消后仍有队列消息与配额突降，并报告排队时间和任务完成时间，而不只报告每秒领取数。\n\n排队中的Task也需要过期和取消语义。一个报价分析在两小时后开始执行时，原价格窗口可能已经失效；待批准动作等了数日，原资源版本也可能改变。调度成功领取任务前，应重新检查任务是否仍有价值、deadline是否有效和授权是否成立，而不是机械处理所有积压消息。\n\n**实践重点**：交互与批任务分队列；人工等待不占计算；只保留一个恢复权威。\n\n**验证抓手**：测排队公平性、worker退出与重复投递。\n\n**常见误区**：两套调度器互相重试，或批量ingest拖垮在线请求。\n\n[Temporal：执行状态与外部副作用](https://docs.temporal.io/ai/featured/memory-state-stripe)；[OpenAI：托管Agents架构](https://developers.openai.com/api/docs/guides/agents-api/architecture)。",
      "blueprint": {
        "inputs": [
          "Task队列与优先级",
          "资源和模型配额",
          "Run租约及deadline"
        ],
        "steps": [
          "按租户与类型排队",
          "原子领取并分配租约",
          "释放等待任务资源",
          "重调度失败执行"
        ],
        "outputs": [
          "获准运行的Run",
          "排队与背压指标",
          "可恢复等待状态"
        ]
      },
      "citations": [
        {
          "url": "https://docs.temporal.io/ai/featured/memory-state-stripe",
          "label": "Temporal：执行状态与外部副作用",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://developers.openai.com/api/docs/guides/agents-api/architecture",
          "label": "OpenAI：托管Agents架构",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": [
        {
          "target": "execution-run",
          "type": "requires",
          "reason": "本节点的设计需要先明确执行Run。"
        },
        {
          "target": "lease-fencing",
          "type": "requires",
          "reason": "本节点的设计需要先明确租约与Fencing。"
        }
      ]
    },
    {
      "id": "knowledge-provenance-versions",
      "title": "原件、版本与来源链",
      "aliases": [
        "provenance",
        "lineage",
        "document version"
      ],
      "kind": "concept",
      "parentId": "knowledge-lifecycle",
      "order": 80,
      "summary": "source object与不可变document version、内容指纹、采集/发布/生效时间、派生lineage。",
      "question": "知识更新后如何知道答案来自哪一版原件？",
      "body": "### 身份稳定，版本不可变\n\n同一份政策修改后仍是同一个源对象，却已经是不同的证据版本。建议将source object ID、document version ID和内容hash分开：前者追踪身份，中间项固定某次状态，hash帮助判断内容是否相同。不能以标题相同认定版本相同，也不能因内容相同合并不同用户的授权边界。\n\n原件、解析结果、chunk、embedding、社区摘要和记忆项组成一张派生关系网。回答所用证据应能沿着这张网回到原始文件及页段，知道它何时被观察、解析和发布。图数据库中的一条边或模型生成的摘要，仍不能替代底层原始证据。\n\n### 至少记录三组时间\n\n源更新时间、系统接入时间和业务生效时间承担不同作用。今天上传的旧政策未必今天才生效，今天修订的财务数据也未必是历史决策当时可知的数据。页面上显示“最新”必须有明确口径，不应把抓取时间当事实发生时间。\n\n对象存储可保存不可变原件与解析JSON，关系库保存版本、状态、权限和派生引用。更新时先完整构建新版本，再切换活动指针；旧版本可以按保留合同归档，以支持历史复核。跨库发布方式在增量发布与一致性节点中展开。\n\n### 来源链的验证边界\n\nMicrosoft Graph的delta是追踪源对象变化的一种实现；GraphRAG则说明同一原文还会派生实体和社区报告。两者提示来源管理要跨越多个加工阶段，而不是只给最终答案附一个URL。本文的字段组织是工程建议，不声称来源产品默认完整实现该合同。\n\n验收时任选一条结论，检查是否能定位原件版本、解析版本、检索证据及访问范围；再修改或撤回源对象，确认依赖它的派生物被标为过期。链接能打开、原文曾读过、结论得到支持和事实仍然有效，应分别记录。",
      "blueprint": {
        "inputs": [
          "稳定源对象ID",
          "原件与加工版本"
        ],
        "steps": [
          "保存不可变快照和时间语义",
          "建立chunk/向量/摘要派生关系",
          "将每次回答绑定明确证据版本"
        ],
        "outputs": [
          "可审计来源链",
          "历史复核与撤回依据"
        ]
      },
      "citations": [
        {
          "url": "https://learn.microsoft.com/en-us/graph/api/driveitem-delta?view=graph-rest-1.0",
          "label": "Microsoft Graph：driveItem delta",
          "kind": "official-doc"
        },
        {
          "url": "https://microsoft.github.io/graphrag/index/overview/",
          "label": "Microsoft GraphRAG：索引管线",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "memory-write-admission",
          "type": "feeds",
          "reason": "记忆候选必须有来源"
        },
        {
          "target": "storage-object-artifacts",
          "type": "complements",
          "reason": "对象存储可以承载原件版本；来源身份、定位与资格仍需元数据合同共同管理。"
        }
      ]
    },
    {
      "id": "lease-fencing",
      "title": "租约与Fencing",
      "en": "Lease and Fencing",
      "aliases": [
        "执行租约",
        "防旧写入"
      ],
      "kind": "concept",
      "parentId": "runtime-task-session",
      "order": 80,
      "summary": "限制同一可变执行状态的有效写入者并拒绝旧worker。",
      "question": "旧worker恢复后，怎样阻止它继续提交过期工作？",
      "body": "限制同一可变执行状态的有效写入者并拒绝旧worker。\n\n租约表示某个worker在一段时间内拥有执行资格；fencing token用来拒绝已经过期的旧worker。只设置超时并不够：进程可能因网络暂停错过续租，随后恢复并继续工作。系统需要一个可比较的代次，确保新owner接管后旧代次不能再提交状态。\n\n领取任务时可原子增加执行代次，之后的状态更新携带该token。数据库或工具网关在真正写入点检查它是否仍有效。若仅在worker开始时检查一次，长工具执行期间租约失效仍可能产生竞态。时间比较应由权威服务完成，不能依赖客户端时钟声明租约有效。\n\nfencing不自动解决外部副作用。目标系统如果不认识token，旧worker已发出的邮件、工单或交易请求仍可能生效。应在网关提交前重新核验，并结合稳定业务操作ID、接收端幂等和外部read-back。对于无法查询且无法幂等的高风险操作，宁可暂停人工对账，也不要因为租约换了owner就自动重放。\n\n并非所有对象都需全局锁。独立资源可以并行，单个Session或可变记录可用单写者、compare-and-swap或资源级锁。测试故意暂停旧worker、让租约过期、新worker接管后再恢复旧进程，观察本地提交、工具调用与外部结果是否都符合约束。否则“有锁”只是一项实现描述，不是重复效果不会发生的证据。\n\n可在日志中记录worker身份、token、取得和失效时间，以及每次提交被接受或拒绝的原因。运行代次是控制信息，不需要交给模型自由填写。对于多个资源的联动更新，单个Run租约还不够；资源版本、数据库事务或明确补偿流程仍然必要，不能把执行owner唯一误认为业务更新原子。\n\n同一token的多次提交仍需业务去重。控制执行资格和控制动作次数是互补机制，不应互相替代。\n\n**实践重点**：租约带单调token，在网关或目标写入点核验；外部副作用仍需幂等。\n\n**验证抓手**：制造租约过期后旧worker复活，检查写入和外部调用。\n\n**常见误区**：只锁本地状态，却认为旧worker不可能继续调用外部工具。\n\n[Temporal：执行状态与外部副作用](https://docs.temporal.io/ai/featured/memory-state-stripe)；[DeepSeek Harness：事件日志驱动循环](https://github.com/deepseek-ai/deepseek-harness/blob/86a402200d95fecef4529d969836f1fe13c6cb0d/packages/core/agent-loop/src/agent.ts#L42-L168)。",
      "blueprint": {
        "inputs": [
          "当前执行代次",
          "worker租约",
          "目标资源版本"
        ],
        "steps": [
          "原子领取新代次",
          "持续核验租约",
          "在写入点拒绝旧token",
          "对外部动作保留幂等"
        ],
        "outputs": [
          "单一有效写入者",
          "被拒绝旧提交",
          "外部效果对账记录"
        ]
      },
      "citations": [
        {
          "url": "https://docs.temporal.io/ai/featured/memory-state-stripe",
          "label": "Temporal：执行状态与外部副作用",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://github.com/deepseek-ai/deepseek-harness/blob/86a402200d95fecef4529d969836f1fe13c6cb0d/packages/core/agent-loop/src/agent.ts#L42-L168",
          "label": "DeepSeek Harness：事件日志驱动循环",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        }
      ],
      "links": [
        {
          "target": "execution-run",
          "type": "requires",
          "reason": "本节点的设计需要先明确执行Run。"
        },
        {
          "target": "idempotent-side-effects",
          "type": "requires",
          "reason": "本节点的设计需要先明确业务副作用幂等。"
        }
      ]
    },
    {
      "id": "memory",
      "title": "Agent记忆",
      "aliases": [
        "memory",
        "长期记忆",
        "Agent记忆"
      ],
      "kind": "domain",
      "parentId": null,
      "order": 80,
      "summary": "事实、经历、任务连续性及受治理的记忆表示与操作。",
      "question": "跨Session信息怎样被准入、回忆、修正和遗忘？",
      "body": "Agent记忆保存跨会话仍有用的信息，但不能把所有历史、企业知识和执行状态混成一个向量库。事实与偏好、任务经历、任务理解投影和程序性技能分别具有不同写入、复用及撤回规则。\n\nSession和checkpoint负责恢复实际执行位置，Task摘要帮助模型理解目标与进度，长期memory负责在合格范围内复用事实和经历。正式企业制度仍由知识源维护，普通聊天不能改写它；检索到记忆也不会产生当前动作授权。\n\n本分支从内容类型、表示与召回进入准入、时间冲突、并发、遗忘和投毒防护。衡量记忆价值的不是存了多少，而是后续任务是否使用了正确、允许且仍有效的信息。程序经验成为可复用能力时，还应经过独立的评测与发布流程。",
      "blueprint": {
        "inputs": [
          "交互、任务与来源证据",
          "记忆类型和作用范围"
        ],
        "steps": [
          "提炼候选并准入",
          "按任务召回有限数据",
          "更正、过期、撤回并评估"
        ],
        "outputs": [
          "可治理的跨会话信息",
          "可复核而非无限增长的经验"
        ]
      },
      "citations": [
        {
          "url": "https://docs.langchain.com/oss/python/concepts/memory",
          "label": "LangChain：记忆分类",
          "kind": "official-doc"
        },
        {
          "url": "https://help.getzep.com/v4/memory-security",
          "label": "Zep v4：记忆安全边界",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "memory-task-continuity",
      "title": "跨会话任务连续性",
      "aliases": [
        "task memory",
        "handoff summary",
        "任务连续性"
      ],
      "kind": "concept",
      "parentId": "memory-types",
      "order": 80,
      "summary": "任务摘要投影：目标/约束/已验证结论/失败尝试/依赖/下一步与归档。",
      "question": "换一个Session后如何继续同一任务而不丢目标和验收？",
      "body": "### 下一次Session需要知道当前任务到哪里\n\n跨会话工作不能只保存最后一句回复。新的Session需要理解目标、验收条件、已确认约束、完成项、未解决问题、失败尝试、依赖和下一步。Task memory的作用是形成易读的任务投影，让模型迅速恢复理解，而不是替代权威执行状态。\n\nAnthropic关于长期Agent harness的文章讨论跨context window继续工作的困难，并以进度文件、明确功能列表和增量产物衔接会话。它是一个实现案例，不能据此认为任意自然语言摘要都能可靠恢复复杂业务操作。\n\n### 摘要与checkpoint分别负责什么\n\n摘要可解释为什么选择某路线，checkpoint应保存实际执行位置、工具call身份、审批和预算等显式状态。摘要说“付款已完成”不应触发跳过业务读回；若原始事件显示结果未知，下一轮必须按结果未知处理，而不是相信流畅叙述。\n\n建议任务摘要引用稳定事件和artifact ID，保留已验证事实与模型推断的区别。压缩时优先保留未完成目标、最新用户纠正、禁止动作、关键依赖及验证缺口；已失效计划可以归档，但不能把尚未执行的计划写成完成事实。\n\n### 任务结束后改变记忆用途\n\n任务归档不意味着其中所有内容都成为长期个人偏好或团队技能。客户事项事实应留在原scope，通用经验需单独抽取和审查；短期临时条件不应跨到下一个无关任务。多个Session可以属于同一Task，但仍需独立身份与授权。\n\n验收让任务在不同阶段中断：工具执行前、结果未知时、验证失败后和用户纠正后。新Session应继续正确步骤，并能定位已有证据，避免重复副作用、丢失验收或过早宣布完成。摘要质量指标应服务这些行为，而非只看压缩率。",
      "blueprint": {
        "inputs": [
          "权威Task状态与事件",
          "证据、产物和未完成目标"
        ],
        "steps": [
          "提炼可读任务投影",
          "保留事件引用与不确定状态",
          "新Session对照checkpoint继续"
        ],
        "outputs": [
          "跨Session理解连续性",
          "不替代checkpoint的任务摘要"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents",
          "label": "Anthropic：长期Agent harness",
          "kind": "official-doc"
        },
        {
          "url": "https://docs.langchain.com/oss/python/concepts/memory",
          "label": "LangChain：Memory overview",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "business-task",
          "type": "requires",
          "reason": "摘要引用权威任务合同"
        },
        {
          "target": "checkpoint-recovery",
          "type": "complements",
          "reason": "摘要辅助理解但不能替代恢复状态"
        },
        {
          "target": "context-assembly",
          "type": "feeds",
          "reason": "跨会话摘要是压缩输入之一"
        }
      ]
    },
    {
      "id": "model-context-protocol",
      "title": "MCP",
      "en": "Model Context Protocol",
      "aliases": [
        "MCP",
        "工具连接协议"
      ],
      "kind": "concept",
      "parentId": "runtime-tools",
      "order": 80,
      "summary": "标准化工具与数据连接的协议。",
      "question": "标准化工具连接之后，哪些信任与权限工作仍要做？",
      "body": "标准化工具与数据连接的协议。\n\nMCP为模型应用连接工具和数据提供标准协议。它有助把连接方式与单个模型或聊天界面分离，但不决定企业中谁可以访问什么，也不保证server返回内容可信。企业采用MCP时，仍要把远端能力放入自己的身份、数据和发布治理。\n\n连接前确认server主体、部署位置、工具定义和版本，按任务核查OAuth audience、scope及重定向。不要把用户授给某服务的token无条件透传给另一服务，也不要把应用状态句柄当登录身份。工具目录变化会改变Agent能力，需要评估模型是否选错工具、schema是否兼容及权限是否扩大。\n\n远端返回数据可能带有恶意指令，不能直接改写应用规则或memory。调用结果经过输出大小、敏感数据和来源处理后，再进入context。若server在内部持有更多权限，必须防止confused deputy：调用者只能请求其自身被允许的资源，而非借server身份读取其他租户。\n\n本地server安装和更新也是供应链边界。公开repo、MCP徽章或连接成功不能代替代码与许可审查；企业私有资料不应发送给未经核实的demo。验证既测协议兼容，也测错误audience、过宽scope、工具定义替换、结果投毒和断线恢复。标准解决互通，可信执行仍是平台责任。\n\n对远程连接，审计还应记录请求最终去了哪个server和版本，而非只保存一个显示名。相同工具名可能在不同组织或环境指向不同资源。连接配置、凭证scope和工具目录应作为发布资产管理，生产切换不能只靠修改本地环境变量后默认继续运行。\n\n采用连接器时，应区分协议规范、SDK实现、远端server和具体工具四层证据。某一层通过兼容测试，不意味着其余层的授权与业务结果也得到验证。每层都应保存版本和责任owner。\n\n**实践重点**：核验server身份、定义、授权scope与网络目的地；版本变更纳入发布。\n\n**验证抓手**：用错误audience、token透传与定义变更做安全契约测试。\n\n**常见误区**：把符合MCP视为server可信或自动具备企业权限。\n\n[MCP：当前规范](https://modelcontextprotocol.io/specification/latest)；[MCP：安全建议](https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices)。",
      "blueprint": {
        "inputs": [
          "MCP server身份与定义",
          "授权token和scope",
          "应用工具治理规则"
        ],
        "steps": [
          "验证连接及授权对象",
          "登记工具版本",
          "经网关调用并过滤结果",
          "监测定义和权限变化"
        ],
        "outputs": [
          "标准化工具连接",
          "受控数据结果",
          "安全与兼容性记录"
        ]
      },
      "citations": [
        {
          "url": "https://modelcontextprotocol.io/specification/latest",
          "label": "MCP：当前规范",
          "kind": "standard",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices",
          "label": "MCP：安全建议",
          "kind": "standard",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": [
        {
          "target": "tool-contract",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具接口合同。"
        },
        {
          "target": "tool-authorization",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具授权网关。"
        }
      ]
    },
    {
      "id": "retrieval-dense-embeddings",
      "title": "向量表示与Embedding选择",
      "aliases": [
        "embedding",
        "dense retrieval",
        "向量模型"
      ],
      "kind": "concept",
      "parentId": "retrieval-pipeline",
      "order": 80,
      "summary": "向量空间、query/document指令、维度归一化、候选模型档位和业务gold set。",
      "question": "怎样选适合中英混写与企业术语的向量模型？",
      "body": "### 选择的是一份表示合同\n\nEmbedding把query和文档映射到可比较的向量空间，适合发现措辞不同但含义接近的材料。它不能自动理解全部企业缩写，也不保证精确区分两个合同编号。模型选择应围绕实际资料与问题，而不是只比较一个综合榜单或向量维度大小。\n\nBGE-M3公开模型卡描述dense、sparse与multi-vector能力；Qwen3 Embedding系列提供不同大小档位。它们是可评估候选，不是对金融、法律或教育资料精度的证明。开放权重模型也可以运行在托管云推理服务上，无需先把企业系统全部私有化。\n\n### 所有预处理都影响向量空间\n\n保存模型revision、维度、query/document指令、归一化、距离函数、tokenizer、截断和量化策略。输入标题、章节路径还是正文，是否去掉表格，以及长文本如何裁剪，都会改变表示。相同维度的不同模型向量不能直接混合比较。\n\n建议至少比较一个托管服务、一个较小开放权重模型和一个较大候选。用相同文档、切块、授权条件和query评估中文术语、英文缩写、中英混写、跨语言、编号及表格。质量之外记录query延迟、批量吞吐、资源、许可与固定版本能力。\n\n### 保留独立的词法路线\n\n向量分数受模型与数据分布影响，不是校准后的事实置信度。提高top-k可能增加召回，也可能让大量重复或泛相关内容挤占上下文。若正确资料根本没被解析或索引，升级embedding无法修复这一缺口。\n\n验收应先看相关证据召回，再看重排与最终答案。为确切ID和时间约束保留结构字段；更换模型时先双索引影子评估，再切换查询向量和文档索引，不应在线混用两代空间。",
      "blueprint": {
        "inputs": [
          "统一切块后的文档",
          "带术语和语言分层的gold queries"
        ],
        "steps": [
          "冻结表示与预处理合同",
          "比较质量、吞吐、延迟和许可",
          "选择候选并独立版本化"
        ],
        "outputs": [
          "文档和query向量",
          "可回滚的embedding revision"
        ]
      },
      "citations": [
        {
          "url": "https://huggingface.co/BAAI/bge-m3",
          "label": "BGE-M3模型卡",
          "kind": "official-doc"
        },
        {
          "url": "https://arxiv.org/abs/2506.05176",
          "label": "Qwen3 Embedding技术报告",
          "kind": "paper"
        }
      ],
      "links": [
        {
          "target": "retrieval-hybrid-fusion",
          "type": "feeds",
          "reason": "dense与词法召回互补"
        },
        {
          "target": "retrieval-embedding-migration",
          "type": "complements",
          "reason": "更换Embedding后需要迁移策略；初次建立向量表示不以迁移为前置。"
        }
      ]
    },
    {
      "id": "sandbox-lifecycle",
      "title": "沙箱生命周期",
      "en": "Sandbox Lifecycle",
      "aliases": [
        "环境生命周期",
        "受限执行"
      ],
      "kind": "concept",
      "parentId": "runtime-harness",
      "order": 80,
      "summary": "计算与文件环境的创建、使用、隔离、保留和销毁合同。",
      "question": "计算环境损坏或销毁后，哪些状态必须仍可恢复？",
      "body": "计算与文件环境的创建、使用、隔离、保留和销毁合同。\n\n沙箱是运行代码和处理文件的环境，不应承担唯一的业务真相。环境可以因超时、容量或供应商故障被销毁；Task状态、操作身份和最终产物必须存放在独立的持久系统。恢复时应能根据已提交记录重建环境，而不是希望模型记得上一次临时目录里的内容。\n\n托管Agent公开工程中，harness、session日志与sandbox可以有不同生命周期。Meta Muse披露的用户VM和cell外权限权威，又显示隔离粒度可以是用户而非每个角色。企业需要明确环境属于租户、项目、任务还是某次Run；一个账号内多个Bot并不必然拥有独立磁盘或浏览器登录。\n\n环境合同包括镜像版本、允许挂载、网络目的地、CPU与内存、执行时限、依赖安装和空闲保留。生产凭证优先由网关代持，临时授权绑定scope和Task。产物离开沙箱前保存内容hash、媒体类型和访问策略。checkpoint恢复不应自动恢复已经撤回的凭证或来源权限。\n\n容器、microVM和托管sandbox有不同隔离与运维成本，不能只看冷启动速度。长时间预热会增加费用和敏感快照保留面；共享环境可提高复用，却需要可见的共享边界。测试应覆盖环境崩溃、重新挂载、受限出网、资源耗尽与销毁后数据可恢复性，并明确哪些临时文件不会保留。\n\n例如同一任务创建第二个Run时，可以复用已审阅的输入文件和依赖镜像，但不应自动复用旧浏览器登录、开放端口和过期凭证。文件复用、计算预热、身份授权是三项独立决定。教育班级与法律客户的任务尤其要明确环境清理和共享策略；看见不同聊天头像不意味着底层已经隔离。\n\n环境资源、应用数据和授权凭证应各有保留策略，并记录执行镜像的来源。\n\n**实践重点**：持久产物外置；短期凭证与任务绑定；损坏后从已提交状态重建。\n\n**验证抓手**：测试环境崩溃、重新挂载、出网与凭证边界。\n\n**常见误区**：把沙箱磁盘当唯一状态，或把不同角色误当隔离环境。\n\n[OpenAI：托管Agents架构](https://developers.openai.com/api/docs/guides/agents-api/architecture)；[Anthropic：Managed Agents工程设计](https://www.anthropic.com/engineering/managed-agents)。",
      "blueprint": {
        "inputs": [
          "环境镜像与隔离策略",
          "Task资源和授权scope",
          "持久产物引用"
        ],
        "steps": [
          "创建受限环境",
          "挂载必要输入",
          "执行并导出产物",
          "清理或按策略保留"
        ],
        "outputs": [
          "可重建运行环境",
          "持久产物与hash",
          "销毁及保留记录"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/agents-api/architecture",
          "label": "OpenAI：托管Agents架构",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://www.anthropic.com/engineering/managed-agents",
          "label": "Anthropic：Managed Agents工程设计",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": [
        {
          "target": "checkpoint-recovery",
          "type": "requires",
          "reason": "本节点的设计需要先明确Checkpoint与恢复。"
        },
        {
          "target": "tool-authorization",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具授权网关。"
        }
      ]
    },
    {
      "id": "storage-milvus",
      "title": "Milvus与分布式向量系统",
      "aliases": [
        "Milvus",
        "distributed vector search"
      ],
      "kind": "product",
      "parentId": "storage-engines",
      "order": 80,
      "summary": "Lite/Standalone/Distributed边界、存算/WAL分离、吞吐扩展和运维故障域。",
      "question": "什么时候分布式向量扩展收益能覆盖额外复杂度？",
      "body": "### 大规模扩展需要整个系统支撑\n\nMilvus面向向量检索，官方架构说明其存储与计算解耦，并涉及WAL、对象存储和多个服务角色。独立扩展能力可以服务高吞吐或大型资料集，但不意味着一个本地demo就证明分布式生产运维简单。Lite、Standalone与Distributed应分别评估。\n\n团队若云优先，可以比较托管形态以减少集群维护；仍需掌握数据schema、索引配置、备份恢复和导出。数据库本身负责向量检索，不会自动提供任务状态机、来源权威或企业动作授权。\n\n### 过滤策略影响路径\n\nMilvus官方区分标准过滤与迭代过滤：前者先限定数据范围，后者迭代生成向量候选并检查条件。复杂表达式、选择率和语义相关性会影响哪种更合适，因此应在实际资料和授权分布下比较，而不是只选择一个名字看起来更新的算法。\n\n分布式查询还要考虑shard、数据加载、冷暖状态、更新可见性和故障后的恢复。对象存储降低某些持久化负担，却可能增加读取延迟；WAL保障和索引服务状态也应进入端到端故障演练。\n\n### 让需求证明复杂度值得\n\n适合进入评估的触发包括：单库资源边界已被真实负载证明、需要持续大量向量更新、检索吞吐或多向量规模成为核心瓶颈。不要仅依据“达到百万条”就迁移；低维热数据与高维多向量文档的成本结构完全不同。\n\n验收在并发读写、冷加载、重建和节点故障下测过滤召回、p95、吞吐及恢复时间，同时统计依赖组件成本与团队操作负担。只有质量和运行合同都达到目标，扩展能力才是实际收益，而不只是架构图上多了几个可伸缩方块。",
      "blueprint": {
        "inputs": [
          "规模、维度、更新与并发模型",
          "部署形态和恢复目标"
        ],
        "steps": [
          "选择Lite/Standalone/Distributed或托管形态",
          "比较过滤和索引策略",
          "演练加载、更新与节点故障"
        ],
        "outputs": [
          "可解释的扩展方案",
          "质量、容量与恢复证据"
        ]
      },
      "citations": [
        {
          "url": "https://milvus.io/docs/architecture_overview.md",
          "label": "Milvus：架构",
          "kind": "official-doc"
        },
        {
          "url": "https://milvus.io/docs/filtered-search.md",
          "label": "Milvus：过滤搜索",
          "kind": "official-doc"
        },
        {
          "url": "https://github.com/milvus-io/milvus/blob/master/LICENSE",
          "label": "Milvus LICENSE",
          "kind": "code",
          "note": "许可范围按实际使用的版本、路径及分发包再次核对。"
        }
      ],
      "links": [
        {
          "target": "storage-capacity",
          "type": "requires",
          "reason": "由维度/并发/更新/冷热模型驱动"
        },
        {
          "target": "retrieval-filtered-ann",
          "type": "implements",
          "reason": "标准与迭代过滤需实测"
        },
        {
          "target": "storage-managed-procurement",
          "type": "complements",
          "reason": "托管形态与自运维分开比较"
        }
      ],
      "productRoute": {
        "vendor": "Milvus社区 / 托管服务商",
        "category": "分布式向量系统",
        "execution": "向量及过滤搜索",
        "orchestration": "应用编排；集群内部多服务",
        "context": "dense/sparse与不同过滤策略",
        "persistence": "WAL、对象存储及计算层分离",
        "modelBoundary": "模型表示与索引配置固定",
        "deployment": "Lite/Standalone/Distributed或托管",
        "license": "核心Apache-2.0；托管合同独立",
        "availability": "公开部署形态；托管能力依服务商",
        "strengths": "面向大规模伸缩的架构",
        "limits": "组件复杂度、冷加载和恢复需验证"
      }
    },
    {
      "id": "agent-cancellation",
      "title": "取消语义",
      "en": "Agent Cancellation",
      "aliases": [
        "中断",
        "停止任务"
      ],
      "kind": "concept",
      "parentId": "runtime-task-session",
      "order": 90,
      "summary": "停止新行动并记录已开始操作的最终或未知结果。",
      "question": "用户停止任务时，如何处理已开始或已生效的动作？",
      "body": "停止新行动并记录已开始操作的最终或未知结果。\n\n取消是一种控制请求，不是现实世界的回滚。用户停止研究，可以阻止下一次模型调用；正在执行的只读查询可能可中断；已经发送的消息或成功创建的记录则不能靠取消Run自动撤回。界面与状态机必须分别表达这些结果。\n\nOpenCode固定研发源码允许provider与tool fibers被中断，同时保护最终工具和step事件发布。这个细节很重要：工作停止后，系统仍需要记录已经发生或尚不确定的动作。若为了快速响应取消而跳过所有最终写入，就可能留下外部成功、内部未知的孤儿操作。\n\n建议区分cancel_requested、已停止新动作、工具取消确认、结果未知和不可撤销已完成。收到取消后先阻止新排队与新权限提交，再向可中断操作传播信号；对已经发出的写操作继续获取最小必要回执或进行对账。用户若要求补偿，应创建新的授权动作，不把补偿假装成原操作从未发生。\n\n多Agent场景还要定义父取消如何传递到子任务，以及独立后台任务是否属于同一取消范围。关闭聊天窗口也不应被默认为取消所有Task。测试在模型输出、工具调用、批准等待与子Agent合并四个阶段分别取消，检查费用、事件完整性、后续动作和用户可见解释。最有用的反馈是“停止了什么、哪些已发生、哪些仍需确认”。\n\n取消确认还应说明预算会怎样结算。已发出的模型请求和工具工作可能仍产生费用，供应商也未必提供立即终止所有底层计算的保证。产品应根据实际回执显示状态，不承诺“点击停止即零费用”。对于仍在确认效果的动作，保留可见入口，让用户避免重复发起同一工作。\n\n**实践重点**：区分取消请求、可中断工作和不可撤销效果；保留最终状态写入。\n\n**验证抓手**：在模型流和工具执行期间取消，检查账本与回执。\n\n**常见误区**：把任务cancelled误当撤销邮件、交易或已写业务记录。\n\n[OpenCode：流、工具和取消源码](https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/runner/step.ts#L32-L245)；[Agents SDK：Session接口源码](https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/memory/session.py#L53-L94)。",
      "blueprint": {
        "inputs": [
          "用户取消范围",
          "在途模型与工具调用",
          "已提交副作用记录"
        ],
        "steps": [
          "阻止新行动",
          "传播中断信号",
          "收集最终或未知结果",
          "按需创建补偿任务"
        ],
        "outputs": [
          "取消状态与原因",
          "已发生效果清单",
          "待对账操作"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/anomalyco/opencode/blob/f40dc433cb52eeb3ff5ec7a755f0ba0162216a51/packages/core/src/session/runner/step.ts#L32-L245",
          "label": "OpenCode：流、工具和取消源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        },
        {
          "url": "https://github.com/openai/openai-agents-python/blob/17d994bd3045dae71acda676a4ef4762ed8ecd94/src/agents/memory/session.py#L53-L94",
          "label": "Agents SDK：Session接口源码",
          "kind": "code",
          "note": "观察基线：2026-10-15；固定源码与具体发行版本分别核验。"
        }
      ],
      "links": [
        {
          "target": "unknown-operation-outcome",
          "type": "requires",
          "reason": "本节点的设计需要先明确结果未知与对账。"
        },
        {
          "target": "event-log",
          "type": "requires",
          "reason": "本节点的设计需要先明确事件日志。"
        }
      ]
    },
    {
      "id": "agent-to-agent-protocol",
      "title": "A2A",
      "en": "Agent-to-Agent Protocol",
      "aliases": [
        "A2A",
        "Agent互操作"
      ],
      "kind": "concept",
      "parentId": "runtime-tools",
      "order": 90,
      "summary": "面向独立Agent之间能力与任务互操作的协议。",
      "question": "Agent能互通后，怎样确认任务责任和真实交付？",
      "body": "面向独立Agent之间能力与任务互操作的协议。\n\nA2A面向独立Agent之间的互操作，帮助表达能力、任务状态和产物。它与MCP的侧重点不同：MCP常用于工具和数据连接，A2A处理Agent之间的任务交互。二者可以互补，但都不自动完成企业授权、结果验证或商业责任分配。\n\n首先判断是否真的跨独立信任域。如果只是同一个runtime内部的子任务，用直接委派合同可能更简单；只有不同系统、供应商或组织的Agent需要互通时，才引入协议边界。每个参与者应有可核验身份、可用能力、数据范围和超时取消合同，不能仅凭一张能力描述卡就授予执行权。\n\n状态映射要清楚：远端accepted、working、input-required或completed，如何映射本地Task与Run？远端说completed应触发本地verifier，而非直接成功。产物需要来源、媒体类型、内容身份和访问规则；跨Agent返回的文字仍可能有错误或注入，不应提升为高优先级指令。\n\n跨系统失败会带来重复投递、延迟结果、取消竞态和费用分摊。发送任务先保存稳定业务身份，明确谁负责重试与外部效果。验证任务重投、远端失联、取消后完成、权限撤回及产物过期等场景。协议互通成功，只证明消息能够交换，不能证明真实服务已经按约履行。\n\n如果接入付费外部Agent，还要分清任务技术完成、服务被接受、实际交付与收费。一个协议completed状态不能证明客户认可或付款成功。企业控制平面应保存合同、产物验收和必要回执；研究中的benchmark提交、模拟用户和真实付费客户也不能混为采用证据。\n\n协议版本与应用任务schema要分别登记。兼容升级后仍应测试状态映射和结果引用；远端能力发生重大变化时，应重新验证，而不是沿用最初的接入结论。\n\n**实践重点**：显式任务状态、身份与结果合同；企业责任和授权另行定义。\n\n**验证抓手**：验证任务状态映射、取消和产物来源。\n\n**常见误区**：把互通协议当结果正确、商业履约或多Agent自动协作证明。\n\n[A2A：当前规范](https://a2a-protocol.org/latest/)；[MCP：当前规范](https://modelcontextprotocol.io/specification/latest)。",
      "blueprint": {
        "inputs": [
          "远端Agent身份和能力",
          "任务及数据范围",
          "状态与产物合同"
        ],
        "steps": [
          "建立受信连接",
          "提交有稳定身份的任务",
          "映射远端状态",
          "复核产物及责任边界"
        ],
        "outputs": [
          "跨Agent任务记录",
          "可验证产物",
          "取消与失败处理"
        ]
      },
      "citations": [
        {
          "url": "https://a2a-protocol.org/latest/",
          "label": "A2A：当前规范",
          "kind": "standard",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://modelcontextprotocol.io/specification/latest",
          "label": "MCP：当前规范",
          "kind": "standard",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": [
        {
          "target": "business-task",
          "type": "requires",
          "reason": "本节点的设计需要先明确业务Task。"
        },
        {
          "target": "child-agent-contract",
          "type": "requires",
          "reason": "本节点的设计需要先明确子Agent委派合同。"
        }
      ]
    },
    {
      "id": "evaluation",
      "title": "评测、验证与发布",
      "aliases": [],
      "kind": "domain",
      "parentId": null,
      "order": 90,
      "summary": "从任务合同到线上结果，建立可重放评测、独立验证与受控发布闭环。",
      "question": "如何把这项机制变成可执行、可核查的工程合同？",
      "body": "评测衡量一批任务上的表现，验证为一次运行的具体断言提供证据。企业Agent需要同时回答：是否完成业务目标，是否遵守权限和预算，产物能否被独立核查，以及换模型或数据后表现是否仍可信。单一回答评分无法覆盖这些问题。\n\n建议从任务合同、代表性数据和可重放Trial开始，再按终态、工具、轨迹、检索、记忆与安全定位失败。评分层组合确定性验证、语义Judge和专家校准；统计层处理重复可靠性、置信区间与持出污染。最后通过模型升级矩阵、shadow、canary和回滚把证据连接正式发布。\n\n金融、教育与法律应添加各自的时序、学习效果与权威效力标准。通用平台提供一致记录和门禁，领域包定义正确性与风险，任何总分都不能抵消越权或严重事实错误。",
      "blueprint": {
        "inputs": [
          "任务合同",
          "数据与权限快照",
          "Agent版本"
        ],
        "steps": [
          "构建用例与执行trial",
          "分层验证并校准评分",
          "测量不确定性",
          "灰度晋升或回滚"
        ],
        "outputs": [
          "评测报告",
          "验证回执",
          "发布资格"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc",
          "note": "2026-01-09；官方方法背景，具体合同与阈值须按业务验证。"
        }
      ],
      "links": []
    },
    {
      "id": "knowledge-incremental-publishing",
      "title": "增量入库与原子发布",
      "aliases": [
        "incremental ingestion",
        "index generation"
      ],
      "kind": "concept",
      "parentId": "knowledge-lifecycle",
      "order": 90,
      "summary": "阶段job、幂等、游标、待发布版本、active版本切换与回填。",
      "question": "如何更新知识而不把半成品索引暴露给用户？",
      "body": "### 接入完成与可搜索是两个状态\n\n源系统已经下载了一份新文件，不代表知识服务应该立刻切换。解析可能还没完成，部分chunk的embedding失败，倒排与向量索引也可能处于不同版本。若直接原位覆写，用户可能一次查询混用新旧段落，得到不存在于任何正式版本中的答案。\n\n建议把一次入库分成快照、解析、质量检查、切块、索引、发布几个阶段，每阶段有输入hash、处理版本、幂等键、尝试次数和错误状态。新资料先进入未发布generation；只有必需阶段完成，才原子切换active version或alias。\n\n### 对异步失败保持诚实\n\n原始文件与权威元数据可以在事务中确定，而外部检索服务通常需要异步传播。AWS的transactional outbox模式用于解决数据库写入与消息发布之间的双写问题。将待同步事件与业务状态一起提交，后续消费失败可以重放，而不是依赖一次网络调用的返回值维持一致性。\n\n正常内容更新可以保留上一份有效版本继续服务，并展示新鲜度；权限撤回和删除则应先禁用，再处理物理清理。不要用“最终一致”解释撤回之后仍向无权限用户展示内容。不同事件类别应有不同的优先级和最大传播延迟。\n\n### 发布前后都要对账\n\n建立每个源对象的期望版本与每个索引的实际generation，持续检查缺块、残留旧块和孤立向量。若发生重新切块或embedding升级，保留双索引窗口和回滚指针；失败时可以退回完整旧版，不能退回半完成的新状态。\n\n用重复事件、乱序事件、进程重启和外部索引超时验证管线。验收标准是同一对象最终只暴露一套完整、授权正确的活动版本，并能明确列出仍未发布的资料。一次job显示成功不应掩盖其后续发布仍未完成。",
      "blueprint": {
        "inputs": [
          "源对象变化与期望版本",
          "各阶段处理配置"
        ],
        "steps": [
          "构建未发布generation",
          "用幂等job与outbox补齐派生索引",
          "校验完整性后切换活动版本"
        ],
        "outputs": [
          "完整活动索引版本",
          "待发布与失败状态"
        ]
      },
      "citations": [
        {
          "url": "https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html",
          "label": "AWS：Transactional outbox pattern",
          "kind": "official-doc"
        },
        {
          "url": "https://learn.microsoft.com/en-us/graph/api/driveitem-delta?view=graph-rest-1.0",
          "label": "Microsoft Graph：driveItem delta",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "retrieval-embedding-migration",
          "type": "complements",
          "reason": "embedding双索引与发布流程衔接"
        },
        {
          "target": "knowledge-deletion-lineage",
          "type": "complements",
          "reason": "内容发布与撤回有不同优先级"
        }
      ]
    },
    {
      "id": "memory-procedural-skills",
      "title": "程序记忆与可复用技能",
      "aliases": [
        "procedural memory",
        "skill",
        "runbook"
      ],
      "kind": "concept",
      "parentId": "memory-types",
      "order": 90,
      "summary": "runbook/skill的前提/适用范围/验证来源/版本约束及存储；与事实记忆的不同权限。",
      "question": "经验怎样表达成可复用程序而不是永久附加的一段聊天？",
      "body": "### 程序记忆表达怎样做\n\n事实记忆描述“是什么”，经历记忆描述“发生过什么”，程序记忆则描述满足条件时怎样完成任务。可复用runbook或skill应包含适用范围、前置条件、输入输出、工具合同、停止条件、验证步骤和已知反例。它不是一段随对话不断追加的提醒。\n\nLangChain把prompt、代码和模型能力视作程序性行为的一部分；企业系统更需要把可编辑程序与模型权重分开管理。一个技能文件可以版本化、测试和撤回，权重中的行为则需要不同发布与回归机制，不能把两者混称“模型学会了”。\n\n### 从经历推广需要证据\n\n单次成功可能来自偶然输入、人类代劳或错误的成功判据。建议候选skill引用支持它的验证轨迹，并说明在哪些模型、工具和环境版本下成立。具体客户名称、账号或一次性URL通常应参数化，避免把运行实例硬编码成未来规则。\n\nZep v4公开的learning and admission接口展示closed trace到skill candidate再到准入的路线，并支持验证要求和部署版本约束。这证明能力记忆可以拥有工程发布合同，但供应商自动准入的默认选择不应未经评估直接用于金融或法律关键流程。\n\n### 存储与发布不是一回事\n\n本节点关注技能作为记忆的表示：来源、版本、条件和可检索性。离线评测、人工复核、灰度与回滚应由统一能力发布流程执行，普通memory写入工具不能直接修改系统规则或扩大权限。检索到skill也不构成动作授权。\n\n验收比较适用和不适用环境、旧工具版本、撤回源经历和错误候选。一个好skill应让合格任务更有效，同时能在条件不满足时停止或请求帮助；只增加执行自信而没有经过验证的成功提升，不能算积累了新能力。",
      "blueprint": {
        "inputs": [
          "经验证episode与重复任务族",
          "工具合同和适用版本"
        ],
        "steps": [
          "提炼有前提的程序候选",
          "保留来源、参数及反例",
          "交由统一能力准入与发布"
        ],
        "outputs": [
          "版本化runbook或skill",
          "可撤回的程序记忆"
        ]
      },
      "citations": [
        {
          "url": "https://docs.langchain.com/oss/python/concepts/memory",
          "label": "LangChain：Memory overview",
          "kind": "official-doc"
        },
        {
          "url": "https://help.getzep.com/v4/agent-skills/learning-and-admission",
          "label": "Zep v4：Learning and admission",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "memory-episodic-experience",
          "type": "requires",
          "reason": "程序候选源于验证轨迹"
        },
        {
          "target": "prompt-registry",
          "type": "complements",
          "reason": "提示词是程序记忆一种发布物"
        },
        {
          "target": "learning-skill-promotion",
          "type": "feeds",
          "reason": "程序性经验作为候选进入技能准入与发布，不能直接修改已发布能力。"
        }
      ]
    },
    {
      "id": "retrieval-hybrid-fusion",
      "title": "混合召回与排名融合",
      "aliases": [
        "hybrid search",
        "RRF",
        "rank fusion"
      ],
      "kind": "concept",
      "parentId": "retrieval-pipeline",
      "order": 90,
      "summary": "并行候选、去重、RRF与分数归一化、各路排名和候选追踪。",
      "question": "如何组合词法和语义结果而不直接相加不可比的分数？",
      "body": "### 两条召回路解决不同遗漏\n\n用户可能使用自然说法寻找正式术语，也可能给出不能错一位的编号。Dense路线补充语义相近的材料，词法路线保留精确匹配；混合召回的目的，是让两种相关证据都有机会进入候选集。它首先是召回设计，然后才是排名问题。\n\nAzure AI Search与Vespa官方资料都展示全文和向量组合。一个便于分析的起点是并行运行两路查询，对授权候选按稳定证据ID去重，保存各路原始排名，再用RRF等方法融合。不要丢掉分路诊断，否则失败时很难判断是哪条路线提供或压低了关键证据。\n\n### 排名融合不要求原始分数可比\n\nBM25与cosine的取值和意义不同，直接相加会受到分布影响。RRF基于候选排名而非原始尺度，在没有足够校准数据时较易建立基线；线性融合则需要明确归一化、字段与数据分布，不能从一个demo权重推导通用最优比例。\n\n多路召回也可能产生大量同文档相邻段或同一内容的多个副本。去重时保留版本与来源身份，避免将不同权限对象因内容相似合并。可按文档、章节或实体保留候选多样性，但不要为了多样性删除唯一精确命中。\n\n### 用分层消融证明组合价值\n\n比较词法、dense、hybrid及hybrid加rerank四个基线，固定资料、切块和最终证据预算。报告每类query的必需证据召回，而非只展示几条好看的答案。多跳问题还需检查关键证据是否同时齐全。\n\n混合检索增加了调用与候选规模，也可能提高尾延迟。若某类精确查询由词法已可靠解决，可以使用明确路由；复杂问题再采用完整混合管线。最终选择应处于质量、延迟和成功任务成本的可接受前沿。",
      "blueprint": {
        "inputs": [
          "词法与dense候选",
          "稳定证据ID及各路排名"
        ],
        "steps": [
          "并行召回并分别授权",
          "去重后融合排名",
          "保存分路诊断并做消融"
        ],
        "outputs": [
          "统一候选集",
          "可解释的融合排名"
        ]
      },
      "citations": [
        {
          "url": "https://docs.vespa.ai/en/learn/tutorials/hybrid-search",
          "label": "Vespa：混合检索教程",
          "kind": "official-doc"
        },
        {
          "url": "https://learn.microsoft.com/en-us/azure/search/hybrid-search-overview",
          "label": "Azure AI Search：Hybrid search",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "retrieval-lexical-bm25",
          "type": "requires",
          "reason": "词法是混合召回一条路"
        },
        {
          "target": "retrieval-dense-embeddings",
          "type": "requires",
          "reason": "dense是另一条路"
        },
        {
          "target": "retrieval-reranking",
          "type": "feeds",
          "reason": "融合候选进入重排"
        }
      ]
    },
    {
      "id": "storage-weaviate",
      "title": "Weaviate对象与多租户检索",
      "aliases": [
        "Weaviate",
        "ACORN"
      ],
      "kind": "product",
      "parentId": "storage-engines",
      "order": 90,
      "summary": "对象/混合搜索、多租户生命周期、ACORN版本、导入/备份与wl许可路径。",
      "question": "如何评价较高整合度对象检索服务的多租户与版本边界？",
      "body": "### 对象模型与检索整合\n\nWeaviate可作为对象与向量检索整合度较高的候选，适合希望以统一接口管理资料属性、混合搜索和tenant的团队。选择它时应先确定对象身份、原件指针和表示版本，避免把服务内部对象结构直接变成全部业务的唯一schema。\n\n多租户能力需要与租户数量、资料规模、活跃度和隔离合同一起测试。大量小租户与少量大租户有不同成本；冷租户激活、导入、备份和client兼容也会影响实际用户延迟。cloud形态减少运维，但不消除这些接口边界。\n\n### 版本与授权不可凭旧印象\n\n官方1.34发布资料说明新collection默认采用ACORN过滤策略，旧collection仍需核查已有配置。因此升级server不代表所有历史数据自动采用新策略。比较filtered recall时，应记录collection创建方式与实际配置。\n\n截至2026-10-15读取的主仓库LICENSE明确区分路径：wl之外代码为BSD-3-Clause，wl目录及子目录需要单独enterprise license。不能把整个分发包泛称为“全部BSD”，也不能从核心开源许可推出所有云或企业能力免费可用。\n\n### 验证应用真正依赖的部分\n\n基准应使用同一query、过滤、候选数与语义真值，比较混合、向量和重排路径；检查对象更新后旧向量与缓存何时失效。删除原件之后，内部对象、派生摘要及导出是否清理，也要由应用保存进度。\n\n验收还应模拟租户之间相似问题、权限降级、冷激活和恢复。若某项必需能力只在特定套餐或路径内提供，应在采购时固定合同。接口整合度的收益，是减少应用拼装负担；代价是迁移和导出必须提前设计。",
      "blueprint": {
        "inputs": [
          "对象schema与tenant合同",
          "collection配置及拟用功能"
        ],
        "steps": [
          "核对对象、过滤和混合能力",
          "验证历史collection版本与许可路径",
          "测试冷激活、更新和导出恢复"
        ],
        "outputs": [
          "可采购的对象检索方案",
          "明确的版本与授权边界"
        ]
      },
      "citations": [
        {
          "url": "https://docs.weaviate.io/weaviate/manage-collections/multi-tenancy",
          "label": "Weaviate：多租户",
          "kind": "official-doc"
        },
        {
          "url": "https://weaviate.io/blog/weaviate-1-34-release",
          "label": "Weaviate 1.34",
          "kind": "official-doc"
        },
        {
          "url": "https://raw.githubusercontent.com/weaviate/weaviate/main/LICENSE",
          "label": "Weaviate当前LICENSE",
          "kind": "code"
        }
      ],
      "links": [
        {
          "target": "retrieval-hybrid-fusion",
          "type": "implements",
          "reason": "对象检索支持混合搜索"
        },
        {
          "target": "retrieval-filtered-ann",
          "type": "requires",
          "reason": "检查旧collection过滤配置"
        }
      ],
      "productRoute": {
        "vendor": "Weaviate",
        "category": "对象与向量检索",
        "execution": "对象、混合与tenant查询",
        "orchestration": "由应用管理业务任务",
        "context": "对象字段、过滤与混合搜索",
        "persistence": "检索对象不自动取代业务权威模型",
        "modelBoundary": "collection与embedding配置需版本化",
        "deployment": "可采用托管Cloud",
        "license": "wl之外BSD-3-Clause；wl需enterprise license",
        "availability": "按实际版本、路径和套餐核对",
        "strengths": "较高接口整合度",
        "limits": "历史collection配置、冷租户及迁移成本"
      }
    },
    {
      "id": "human-approval",
      "title": "人工审批合同",
      "en": "Human Approval",
      "aliases": [
        "HITL",
        "人工在环"
      ],
      "kind": "concept",
      "parentId": "runtime-task-session",
      "order": 100,
      "summary": "把人类批准绑定到具体动作、资源版本与有效期。",
      "question": "怎样保证批准内容与实际提交的动作完全对应？",
      "body": "把人类批准绑定到具体动作、资源版本与有效期。\n\n审批的对象应是一项具体行动，而非一段笼统计划。用户批准的收件人、金额、文件版本、权限范围与有效期，要能对应到实际提交请求。研究任务继续阅读与向客户发送最终材料，是不同授权动作；企业可预先批准低风险规则，但仍要明确规则适用条件。\n\n可采用prepare、approve、commit、verify四段：先生成变更及证据，服务器校验权限和资源版本，再请求对应角色批准，最后按稳定操作ID提交并读回后置状态。批准绑定规范化请求hash；任何实质参数变化都必须重新核验，不能让模型在批准后修改对象仍沿用原许可。\n\nLangGraph官方文档说明interrupt可等待外部输入，但恢复时node从头重跑。因此interrupt前的副作用要么可幂等，要么拆成独立边界。审批等待可能跨天，原token、ACL、价格和合同状态都可能变化；恢复时检查批准未过期、授权者仍有效、资源版本仍匹配，不能只看一个approved布尔值。\n\n界面应展示差异、来源、风险、可撤销性和实际作用域，让人能够理解决定。拒绝也应记录原因并阻止绕路执行，而非换一个工具或子Agent再试。测试覆盖批准重放、参数篡改、过期、角色撤销和多个并行审批，并证明每个批准只恢复它对应的动作。人工环节的意义在于有内容的控制，而不是在每一步机械弹框。\n\n对低风险、频繁重复动作，可采用范围受限的预批准，例如允许更新某个草稿文件夹中的文档。预批准仍要有owner、作用域和失效条件，不能演变成万能跳过权限开关。产品应区分组织策略、用户一次批准和临时会话许可，让操作审计能还原授权来自哪里。\n\n批准与拒绝的记录本身也属于敏感业务数据，应按角色查看并提供可追溯的保留策略，而非默认公开给所有Agent。\n\n**实践重点**：先prepare再approve与commit；请求变化、过期或授权变化重新核验。\n\n**验证抓手**：变更已批准参数并验证提交被拒绝。\n\n**常见误区**：笼统批准后允许模型改金额、收件人或目标。\n\n[LangGraph：Interrupt与恢复语义](https://docs.langchain.com/oss/python/langgraph/interrupts)；[Claude Code：权限配置](https://code.claude.com/docs/en/permissions)。",
      "blueprint": {
        "inputs": [
          "待提交动作与差异",
          "授权者和业务版本",
          "风险规则及有效期"
        ],
        "steps": [
          "prepare并校验",
          "生成绑定hash的审批",
          "恢复时重新鉴权",
          "commit后验证结果"
        ],
        "outputs": [
          "具体批准或拒绝",
          "稳定操作身份",
          "外部后置状态"
        ]
      },
      "citations": [
        {
          "url": "https://docs.langchain.com/oss/python/langgraph/interrupts",
          "label": "LangGraph：Interrupt与恢复语义",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        },
        {
          "url": "https://code.claude.com/docs/en/permissions",
          "label": "Claude Code：权限配置",
          "kind": "official-doc",
          "note": "公开资料观察基线：2026-10-15。"
        }
      ],
      "links": [
        {
          "target": "tool-authorization",
          "type": "requires",
          "reason": "本节点的设计需要先明确工具授权网关。"
        },
        {
          "target": "idempotent-side-effects",
          "type": "requires",
          "reason": "本节点的设计需要先明确业务副作用幂等。"
        }
      ]
    },
    {
      "id": "knowledge-acl-propagation",
      "title": "知识权限的继承与撤回",
      "aliases": [
        "ACL",
        "permission propagation",
        "security trimming"
      ],
      "kind": "concept",
      "parentId": "knowledge-lifecycle",
      "order": 100,
      "summary": "文档ACL、群组成员、权限revision、检索前过滤和读取原件再授权。",
      "question": "源文档换了权限，旧索引和答案如何同时失效？",
      "body": "### 权限是查询条件，也是证据读取条件\n\n企业检索的相关性必须定义在用户当前有权访问的资料集合内。先召回全库片段、再要求模型不要泄露，已经把内容暴露给了模型；仅在界面隐藏引用也无法撤回进入上下文的信息。身份、群组和资料可见范围应由服务端确定，不由自然语言参数指定。\n\nAzure AI Search的security filter模式展示了按用户或群组标记过滤文档的方法。这是一项实现机制，应用仍需验证principal从何而来、源权限如何继承、群组成员何时更新，以及任何未带过滤的查询是否会被拒绝。\n\n### 撤回路径比新增路径更关键\n\n源文件转为私有、用户离开团队或客户事项结束时，向量、倒排、摘要和缓存可能仍保留旧可见性。建议为ACL和群组成员关系建立revision，变更后使相关查询缓存失效。读取原件、rerank输入和最终引用展开时再授权，拦截索引尚未更新的窗口。\n\n源系统的拒绝规则、继承和例外不能被随意压缩成一个部门字段。多个片段合并成摘要时，摘要的可见范围不能宽于它所依赖的资料；跨权限的GraphRAG社区报告尤其容易泄露原本受限的关系。\n\n### 把拒绝做成可测试合同\n\n对匿名、普通员工、离职用户、跨tenant用户和不同事项成员建立同一组查询。比较返回片段、rerank负载、模型输入、引用和缓存命中，任何一层出现受限正文都应判定失败，而不是只看最终答案是否主动说出了秘密。\n\n再测试权限变化发生在一次长任务中途的情形：任务启动时允许，并不意味着交付时仍允许。旧checkpoint可用于恢复执行证据，却不能冻结已经撤回的权限。正确降级是重新选择可访问证据、停止相关动作或说明资料不可用。",
      "blueprint": {
        "inputs": [
          "服务端身份与群组",
          "源文档ACL及revision"
        ],
        "steps": [
          "同步源授权语义",
          "召回前过滤并在读取/交付时再授权",
          "撤回后失效缓存与派生可见性"
        ],
        "outputs": [
          "当前授权证据集合",
          "可审计拒绝与撤回记录"
        ]
      },
      "citations": [
        {
          "url": "https://learn.microsoft.com/en-us/azure/search/search-security-trimming-for-azure-search",
          "label": "Azure AI Search：Security filter pattern",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "retrieval-filtered-ann",
          "type": "controls",
          "reason": "授权过滤改变ANN召回"
        },
        {
          "target": "memory-scope-isolation",
          "type": "controls",
          "reason": "派生记忆继承可见范围"
        }
      ]
    },
    {
      "id": "learning",
      "title": "能力积累与模型训练",
      "aliases": [
        "learning"
      ],
      "kind": "domain",
      "parentId": null,
      "order": 100,
      "summary": "区分记忆、技能、Harness和权重训练，以独立评测形成能力闭环。",
      "question": "如何积累可迁移能力并保留可验证的发布边界？",
      "body": "Agent积累能力有多条通道：当前context内适应、外部memory、可复用skill、harness变更和模型权重训练。它们改变的对象、数据资格、验证方式与回滚成本不同，应分别治理，不能把对话越存越多统称为模型持续学习。\n\n先从失败轨迹选择最小有效改变，再建立合格数据与独立持出。稳定行为可考虑SFT，可靠偏好可考虑DPO，具备受控环境和奖励时再评估RL；LoRA与QLoRA主要改变参数及资源方式，可服务不同目标。蒸馏还要独立核查教师输出和学生表现。\n\n持续改进把反馈、专家修订、用例、候选diff与发布资格连起来。模型可以提出新方法，但隐藏评分器、权限和正式发布指针属于受信控制层。最终以未见任务、严重错误、成本、延迟和人工负担证明增量收益，并保留撤销能力。",
      "blueprint": {
        "inputs": [
          "目标能力与合格数据"
        ],
        "steps": [
          "定位缺口",
          "提出并验证候选",
          "受控发布"
        ],
        "outputs": [
          "版本化能力与评测证据"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent评测方法",
          "kind": "official-doc",
          "note": "学习收益需在独立业务任务验证。"
        }
      ],
      "links": [
        {
          "target": "models",
          "type": "feeds",
          "reason": "模型、提示与上下文候选通过评测后发布，形成从运行反馈到模型适配的闭环。"
        }
      ]
    },
    {
      "id": "memory-profiles-blocks",
      "title": "Profile与核心记忆块",
      "aliases": [
        "profile",
        "core memory",
        "memory blocks"
      ],
      "kind": "concept",
      "parentId": "memory-representation",
      "order": 100,
      "summary": "小型强schema profile、Letta式always-visible blocks、只读共享与独立事实集的取舍。",
      "question": "哪些记忆应始终放入上下文，哪些只在需要时检索？",
      "body": "### 常驻信息适合小而稳定\n\n用户姓名、明确语言偏好或少量关键团队约定，可能每轮都需要；大量历史事件与领域材料则更适合按需检索。把所有记忆放进常驻profile会持续消耗token，也增加过期信息干扰。Profile是事实的表示方式，不是比来源证据更高的权威层。\n\nLetta的memory block机制把有标签的持久块放入模型上下文，支持共享与只读。它可作为核心记忆的实现参照，但“始终可见”也意味着错误块每轮都会影响行为。数据块不能因被放在prompt前部就升级为系统政策。\n\n### 大档案容易被全量改坏\n\n一个不断增长的JSON档案要求模型每次协调全部旧内容，容易遗漏字段、合并不相关事实或覆盖他人更新。建议把小型profile限制在明确schema与长度，其余事实保存为独立条目；长叙事保留原事件引用，再通过检索找到需要的部分。\n\n块应有owner、scope、version、来源、过期策略和写权限。团队政策可以由中心维护只读块，用户偏好由受控操作更新，临时scratchpad只用于当前任务。共享可写块需要并发合同，不能让多个Agent无版本检查地覆盖同一值。\n\n### 常驻也需要取舍和验证\n\n可比较无profile、有限核心块与全量档案，观察有效信息命中、token、延迟、过期事实使用和更新错误。最重要的测试不是模型能否复述档案，而是用户纠正一个字段后，其他内容保持完整，并且后续任务不再使用旧值。\n\n当记忆变多时，应将低频或已失效内容移出常驻范围，而非无限扩充上下文。返回用户可查看、修正和删除的具体条目；若只展示模型生成的一段综合人设，用户很难定位哪个事实造成了错误行为。",
      "blueprint": {
        "inputs": [
          "小型稳定事实与写权限",
          "核心块schema及长度上限"
        ],
        "steps": [
          "选择真正常用信息",
          "以版本控制块并只读共享政策",
          "将低频经历转为按需检索"
        ],
        "outputs": [
          "受控核心profile",
          "不无限增长的常驻上下文"
        ]
      },
      "citations": [
        {
          "url": "https://docs.letta.com/v1-sdk/memory/memory-blocks",
          "label": "Letta：Memory blocks",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "memory-semantic-facts",
          "type": "complements",
          "reason": "profile是事实表示形式而非新事实类型"
        },
        {
          "target": "memory-recall-policy",
          "type": "complements",
          "reason": "常驻块与按需召回"
        }
      ]
    },
    {
      "id": "retrieval-reranking",
      "title": "候选重排与交叉编码器",
      "aliases": [
        "reranker",
        "cross-encoder",
        "重排序"
      ],
      "kind": "concept",
      "parentId": "retrieval-pipeline",
      "order": 100,
      "summary": "rerank角色、候选数/长度、跨语言与表格输入、质量与延迟取舍。",
      "question": "如何只对少量候选使用更昂贵的相关性判断？",
      "body": "### 把昂贵判断留给小候选集\n\n召回阶段要在大资料集中快速找候选，重排阶段则针对当前query与有限候选进行更细的相关性判断。Cross-encoder可联合读取问题和段落，识别泛相关但不回答问题的材料。不过正确证据若没有进入候选，reranker无法凭空找回。\n\nVespa的first、second和global phase展示了逐步缩小集合再投入更昂贵计算的模式。Cohere当前Rerank文档也提供不同模型档位。选择时应区分模型服务能力、官方自报效果与自己在企业资料上的测量结果。\n\n### 候选长度和数目同样重要\n\n重排输入应包含原问题、必要标题与候选正文。候选过短可能失去定义，过长则增加成本并引入噪声；模型或API的长度限制也可能截断关键脚注。建议记录实际送入的文本与截断位置，而非只保存一个最终相关性分数。\n\n可从候选20、50、100等实验点比较，不把它们视为最佳配置。对长文档、表格、中英混写和多部分问题分别评估。大量近重复段会消耗重排预算，因此去重与候选多样性应在这一阶段之前处理。\n\n### 降级要保留证据边界\n\n重排服务限流或超时时，可以在事先验证的范围内退回融合排名，同时降低证据覆盖承诺；不能为了节省时间跳过授权或用上一用户的排序结果。任务deadline应限制重排的总预算，避免一个慢服务拖垮所有并行检索收益。\n\n验收看最终证据排序与必需证据覆盖，并测负载下p50、p95和错误率。若重排把正确资料挤掉，先查看query、候选和截断，再考虑换模型。没有这些输入记录，最终答案评分无法解释重排究竟改善了什么。",
      "blueprint": {
        "inputs": [
          "授权且去重的候选",
          "原始问题及重排预算"
        ],
        "steps": [
          "构造query-document对",
          "在长度限制内重排",
          "选择高相关且互补证据"
        ],
        "outputs": [
          "重排候选与分数",
          "截断、超时和降级诊断"
        ]
      },
      "citations": [
        {
          "url": "https://docs.vespa.ai/en/ranking/phased-ranking.html",
          "label": "Vespa：多阶段排序",
          "kind": "official-doc"
        },
        {
          "url": "https://docs.cohere.com/v2/docs/rerank",
          "label": "Cohere：Rerank模型文档",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "retrieval-evidence-assembly",
          "type": "feeds",
          "reason": "高相关候选进入上下文"
        }
      ]
    },
    {
      "id": "storage-elastic-search",
      "title": "Elastic与搜索引擎路线",
      "aliases": [
        "Elasticsearch",
        "Elastic Cloud",
        "OpenSearch"
      ],
      "kind": "product",
      "parentId": "storage-engines",
      "order": 100,
      "summary": "全文/向量/过滤统一服务、DLS订阅与配置、Elastic/OpenSearch独立边界、源码与分发许可。",
      "question": "已有全文搜索资产的团队如何接入向量与混合排序？",
      "body": "### 复用已有搜索能力\n\n已有Elastic搜索团队、词法与过滤需求较重的组织，可先比较在现有搜索服务中组合全文、向量和排序。这样可能复用分析器、监控与运维经验，而不必为每个检索方法新增服务。是否划算仍取决于索引成本、订阅和实际召回质量。\n\nElastic当前kNN文档说明filter在近似搜索中作为pre-filter，候选参数与每shard搜索工作量影响准确率。不能把无过滤速度或某个默认候选数当作企业授权检索的保证；多shard合并与冷暖缓存也应进入负载测试。\n\n### DLS是一项需要测试的配置\n\n文档级安全可按角色查询限制可见记录，官方提示省略相应query会取消该索引权限项的DLS约束。应用应检查真实角色组合、索引权限和源ACL传播，而不是只在前端给请求附一个可被绕开的部门字段。\n\n中文分析、精确ID字段、别名、时间与版本应有稳定schema；变化后以新索引/alias管理，避免同一字段语义悄悄改变。对全文、向量与混合路线保留独立结果，才能诊断关键资料在哪里被漏掉。\n\n### 产品与许可保持清楚\n\n免费部分源码可按文件许可在AGPL、SSPL和ELv2之间选择，默认官方分发按ELv2。具体所需DLS或ranking功能是否属于订阅能力，必须单独核查。OpenSearch是独立候选，不能把其当前功能与最新Elastic视作一份产品说明。\n\n验收应包括角色组合、漏写过滤、query改写、索引切换、重建期间的尾延迟与删除传播。搜索相关性、权限正确性、成本和可恢复性分别达标后，复用已有搜索资产才构成完整的选型理由。",
      "blueprint": {
        "inputs": [
          "现有搜索资产与分析器",
          "向量字段、角色和订阅需求"
        ],
        "steps": [
          "建立词法/向量/混合基线",
          "核查kNN过滤与DLS配置",
          "验证alias切换和实际成本"
        ],
        "outputs": [
          "复用搜索服务的可行路线",
          "明确功能与许可资格"
        ]
      },
      "citations": [
        {
          "url": "https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-knn-query",
          "label": "Elastic：kNN查询",
          "kind": "official-doc"
        },
        {
          "url": "https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level",
          "label": "Elastic：文档与字段安全",
          "kind": "official-doc"
        },
        {
          "url": "https://www.elastic.co/pricing/faq/licensing",
          "label": "Elastic：许可FAQ",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "retrieval-lexical-bm25",
          "type": "implements",
          "reason": "搜索引擎承载词法能力"
        },
        {
          "target": "retrieval-hybrid-fusion",
          "type": "implements",
          "reason": "同服务组合不同召回"
        },
        {
          "target": "knowledge-acl-propagation",
          "type": "requires",
          "reason": "DLS与源权限一致"
        }
      ],
      "productRoute": {
        "vendor": "Elastic；OpenSearch为独立候选",
        "category": "全文与向量搜索",
        "execution": "词法、kNN和混合查询",
        "orchestration": "由应用编排",
        "context": "分析器、过滤、DLS与排名",
        "persistence": "搜索索引作为派生层",
        "modelBoundary": "向量字段与模型revision匹配",
        "deployment": "可采用Elastic Cloud",
        "license": "免费源码可选AGPL/SSPL/ELv2；默认分发ELv2",
        "availability": "功能订阅与各版本分别核查",
        "strengths": "复用已有全文搜索和运维资产",
        "limits": "DLS配置、许可、shard与资源成本"
      }
    },
    {
      "id": "domains",
      "title": "金融、教育与法律",
      "aliases": [
        "domains"
      ],
      "kind": "domain",
      "parentId": null,
      "order": 110,
      "summary": "共享执行机制，分别定义金融时序、学习效果与法律权威的成功合同。",
      "question": "这一领域如何定义任务、证据、异常和可验证结果？",
      "body": "企业Agent平台可以复用身份、任务、运行、工具、记忆和发布机制，领域应用仍需独立定义正确性与交付责任。金融投研关心主体、口径和决策时点信息；教育关心学生独立作答、迁移与保持；法律关心法域、引证支持关系和现行效力。\n\n每个领域按端到端流程与专门验证成对展开。先理解输入资格、步骤、异常和用户产物，再进入数值时序、学习效果或法律权威的验收。平台为所有领域提供一致证据链，领域包负责schema、风险、专家rubric和任务结束条件。\n\n三类应用不能共享未经区分的memory、数据分区和总体分数。研究或辅助质量也不能直接等同于投资收益、教学因果效果或正式法律意见。产物应保留来源、时点、未知和人工复核接口，让用户知道哪些结论已经验证，哪些仍需专业判断。",
      "blueprint": {
        "inputs": [
          "领域任务与权限"
        ],
        "steps": [
          "确认范围",
          "收集证据",
          "验证结果"
        ],
        "outputs": [
          "产物与未决项"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：按Agent任务设计评测",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "knowledge-deletion-lineage",
      "title": "删除、墓碑与派生物清除",
      "aliases": [
        "tombstone",
        "right to delete",
        "derived data deletion"
      ],
      "kind": "concept",
      "parentId": "knowledge-lifecycle",
      "order": 110,
      "summary": "tombstone即时禁用、chunk/vector/摘要/图/导出/缓存递归清理、备份恢复后重放。",
      "question": "删原文件为何还不足以让Agent忘掉它？",
      "body": "### 删除是一次全链路操作\n\n从源系统删除文件之后，原文可能仍存在于chunk、向量payload、搜索缓存、回答缓存、摘要、Agent记忆和导出文件中。因此“数据库里已经没有该文件”不足以证明系统停止使用其内容。必须先定义删除语义：停止线上供应、逻辑归档、物理清理和备份保留是不同阶段。\n\n连接器应把源删除作为显式事件处理。Microsoft Graph delta用deleted标记报告删除，展示了接入侧可消费的删除信号；但事件传播到所有派生层仍由应用负责。不能只依靠定期重新embedding来偶然清除旧资料。\n\n### 先禁用，再清理\n\n建议首先在权威对象表写tombstone，使检索入口、原件读取和引用展开立即拒绝使用；随后根据lineage定位各代chunk、embedding、图边、生成摘要、记忆和缓存并异步清理。这样物理删除任务较慢时，也不会继续在线提供已经撤回的内容。\n\n需要为删除事件保存幂等ID、目标版本、原因、消费进度和失败重试。已进入其他任务的材料不能悄悄被当作仍有效证据；恢复旧checkpoint或备份后，也要重放较新的tombstone。否则一次灾难恢复可能把已删除资料重新上线。\n\n### 保留与不可逆边界\n\n是否允许删除原始审计记录、备份保存多久以及第三方导出如何处置，取决于资料域的实际合同。设计上应区分“内容不再可用”与“保留最小删除回执”，回执只需记录对象身份、状态和完成证明，不应再次包含被删正文。\n\n验收可以先用一份包含独特短语的测试文件生成索引、摘要和记忆，再删除它，从所有入口查询短语并检查读取权限；随后模拟索引重建和备份恢复。只有活动服务、派生层和恢复路径均不重新供应该证据，才能报告对应删除合同已经完成。",
      "blueprint": {
        "inputs": [
          "删除事件与源对象ID",
          "完整派生血缘"
        ],
        "steps": [
          "写入tombstone并阻断在线读取",
          "分层清理及幂等重试",
          "恢复后重放删除并验证残留"
        ],
        "outputs": [
          "删除进度与最小回执",
          "不再可供应的证据对象"
        ]
      },
      "citations": [
        {
          "url": "https://learn.microsoft.com/en-us/graph/api/driveitem-delta?view=graph-rest-1.0",
          "label": "Microsoft Graph：driveItem delta",
          "kind": "official-doc"
        },
        {
          "url": "https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html",
          "label": "AWS：Transactional outbox pattern",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "memory-forgetting",
          "type": "complements",
          "reason": "来源删除与记忆撤回联动"
        },
        {
          "target": "storage-outbox-consistency",
          "type": "requires",
          "reason": "删除事件需要跨库传播"
        },
        {
          "target": "storage-object-artifacts",
          "type": "controls",
          "reason": "对象及派生引用受删除事件控制"
        }
      ]
    },
    {
      "id": "memory-write-admission",
      "title": "记忆写入准入",
      "aliases": [
        "memory admission",
        "memory write policy"
      ],
      "kind": "concept",
      "parentId": "memory-governance",
      "order": 110,
      "summary": "候选抽取、schema/来源/敏感性、信任等级、去重矛盾、验证与正式状态。",
      "question": "模型认为值得记住的信息凭什么进入长期记忆？",
      "body": "### 写入会把一次输入变成未来影响\n\n记忆读取失败通常影响当前任务，错误写入却可能在许多后续Session反复出现。因此长期memory不能成为模型自由保存任何文字的便利工具。原始事件可以可靠留存，提炼出的长期事实、偏好与经验则应先进入候选状态。\n\n建议流程为：抽取候选、schema校验、来源与信任检查、敏感性判断、去重和矛盾检测、scope授权、验证状态确认，再进入活动记忆。自动步骤与人工复核可以按类型和风险配置，但普通聊天不能直接写程序规则或扩大工具权限。\n\n### 记录为什么允许保存\n\n每项候选至少说明内容、主体、类型、来源事件、提出者、有效时间、保留期和允许用途。模型自评分只能作为诊断信号，不能替代外部验证。来自正式业务系统、人明确确认、第三方文本或模型推断的信息应有不同信任等级。\n\nZep v4安全文档强调应用决定什么进入memory，并把检索记忆视作非可信数据。这意味着存储服务身份验证与数据隔离不够，应用还需限制模型可调用的写入操作，防止第三方资料把“请永远这样做”包装成用户偏好。\n\n### 用写入质量代替存储量\n\n评估write precision：活动记忆中有多少真实、合格且范围正确；评估write recall：应保留的重要显式信息是否被漏掉。同时测过度推广、敏感误存、错误去重和矛盾处理。更多memory items不等于更强Agent。\n\n验收样本包含用户明确要求记住、临时说法、引用、反讽、第三方指令与纠正。对拒绝的候选保留最小理由与可复核来源，对准入项允许用户查看和撤回。能力候选晋升属于另一套更严格发布流程，不应借事实记忆接口绕过。",
      "blueprint": {
        "inputs": [
          "原始交互与可信来源",
          "scope、类型和保存政策"
        ],
        "steps": [
          "抽取候选并校验schema",
          "检查信任、敏感性、去重与冲突",
          "按类型准入并保存理由"
        ],
        "outputs": [
          "有来源的活动记忆",
          "拒绝或待复核候选"
        ]
      },
      "citations": [
        {
          "url": "https://help.getzep.com/v4/memory-security",
          "label": "Zep v4：Memory security",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "memory-semantic-facts",
          "type": "complements",
          "reason": "事实和偏好需要准入"
        },
        {
          "target": "memory-episodic-experience",
          "type": "complements",
          "reason": "经验保留证据和验证状态"
        },
        {
          "target": "memory-poisoning",
          "type": "complements",
          "reason": "写入门控阻断持续注入"
        },
        {
          "target": "memory-poisoning",
          "type": "controls",
          "reason": "阻断恶意候选写入"
        }
      ]
    },
    {
      "id": "retrieval-chunking",
      "title": "结构切块与父子段",
      "aliases": [
        "chunking",
        "parent-child retrieval",
        "切块"
      ],
      "kind": "concept",
      "parentId": "retrieval-representation",
      "order": 110,
      "summary": "结构边界、token上限、overlap、parent-child与按文档类型策略。",
      "question": "切多大才能既检索精准又保留完整语义？",
      "body": "### 切块同时影响召回和理解\n\n过大的chunk把多个主题混在同一向量里，过小的chunk又可能只剩代词、数值或没有定义的条款。切块应先尊重标题、段落、表格、列表与代码边界，再用token上限约束，而不是把全部文档机械地按相同字符数截断。\n\n建议为chunk保留源版本、章节路径、页码、父段、语言、token数及必要的前置定义。小块用于定位，父段或原页用于理解；parent-child结构允许查询命中精确段后，再按预算读取完整语义范围，而不是无限增加overlap。\n\n### 不同资料采用不同策略\n\nFAQ可按问答对切分，法规条款要保留适用条件，表格按语义行组携带表头，代码按符号与依赖关系组织，聊天记录则需要发言人、时间和线程。原生段落很短时强行补到固定长度，也可能合并本无关联的内容。\n\nAnthropic的Contextual Retrieval文章说明孤立chunk容易丢失全文背景，并提出索引前补充解释。切块与这种增强可组合，但增强文本应标识为派生说明，原文仍是证据。不能因更长context改善检索，就把生成摘要当作正式条款。\n\n### 用真实问题选择粒度\n\n可比较256、512、1024 token及若干overlap比例，这些只是实验点。固定embedding和检索参数，分别测证据召回、重复率、最终token量与答案支持度。中文和英文的token分布不同，必须使用实际tokenizer计数。\n\n失败诊断应区分：原始解析已经丢字，块边界切掉限定条件，召回到了错误块，或证据组装没有补回父段。只提高top-k常会增加重复，无法修复边界错误。验收还应确保引用能回到正确版本与页段，而非只定位到整份文件。",
      "blueprint": {
        "inputs": [
          "带结构的解析文档",
          "文档类型与token预算"
        ],
        "steps": [
          "按语义结构确定边界",
          "保存父子段与定位",
          "用分层query比较粒度和overlap"
        ],
        "outputs": [
          "可定位chunk集合",
          "可补齐的父段关系"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/contextual-retrieval",
          "label": "Anthropic：Contextual Retrieval",
          "kind": "official-doc"
        },
        {
          "url": "https://github.com/docling-project/docling",
          "label": "Docling：结构化文档",
          "kind": "code"
        }
      ],
      "links": [
        {
          "target": "knowledge-document-parsing",
          "type": "requires",
          "reason": "标题/段落结构来自解析"
        },
        {
          "target": "retrieval-contextual-enrichment",
          "type": "feeds",
          "reason": "块上下文增强建立在稳定切块上"
        },
        {
          "target": "retrieval-evidence-assembly",
          "type": "feeds",
          "reason": "父段扩展在证据组装时使用"
        }
      ]
    },
    {
      "id": "storage-vespa-ranking",
      "title": "Vespa与多阶段排序",
      "aliases": [
        "Vespa",
        "rank profile",
        "phased ranking"
      ],
      "kind": "product",
      "parentId": "storage-engines",
      "order": 110,
      "summary": "schema/rank profile、first/second/global phase、分布式serving与学习成本。",
      "question": "何时搜索排序本身值得建设专门的工程能力？",
      "body": "### 当排序本身是产品能力\n\n如果企业产品的核心是复杂搜索或推荐，团队需要精细控制候选匹配、属性、文本、向量和多阶段排名，Vespa值得评估。它提供schema与rank profile表达检索排序，而非仅提供一个最近邻API；收益伴随搜索工程学习和维护成本。\n\n官方phased ranking把便宜的初次评分、较小集合上的second phase以及合并后的global phase分开。这样昂贵模型只作用于最有希望的候选。召回与排序在接口上分工清晰，便于把计算预算显式分配到不同阶段。\n\n### 排序函数不能弥补缺失候选\n\n无论后期模型多强，first phase没有暴露的资料都无法进入重排。候选预算、各路联合方式与每节点限制因此会影响最终质量。跨节点global排序还能处理某些分数归一化，但也增加数据传输和集中计算负担。\n\n建议把业务相关性、权限、时效和可解释属性分开设计，先建立简单基线，再增加复杂特征。离线指标上升不一定代表最终答案更好，特别是出现重复段、受限资料或旧版本时，还需检查证据组装与引用。\n\n### 用全链路负载决定是否采用\n\n评估对象不只是一条rank expression，还包括schema变更、模型部署、内容节点、容器、更新和故障恢复。托管服务可以转移部分运行负担，但团队仍需理解排名阶段、候选数量和业务特征。\n\n验收保存每个阶段的候选与分数，比较新增阶段带来的质量收益和p95成本；模拟某节点延迟、索引更新及模型不可用。若主要需求只是少量内部文档问答，更轻的托管关系库或向量服务可能更易维护；这是工作负载选择，不是对某引擎能力高低的抽象排名。",
      "blueprint": {
        "inputs": [
          "检索schema与业务特征",
          "各阶段候选和计算预算"
        ],
        "steps": [
          "构建简单多路召回",
          "逐阶段加入昂贵排序",
          "测分布式负载与阶段增益"
        ],
        "outputs": [
          "可调控的多阶段检索排序",
          "阶段级质量与延迟诊断"
        ]
      },
      "citations": [
        {
          "url": "https://docs.vespa.ai/en/ranking/phased-ranking.html",
          "label": "Vespa：Phased ranking",
          "kind": "official-doc"
        },
        {
          "url": "https://docs.vespa.ai/en/basics/ranking.html",
          "label": "Vespa：Ranking",
          "kind": "official-doc"
        },
        {
          "url": "https://github.com/vespa-engine/vespa/blob/master/LICENSE",
          "label": "Vespa LICENSE",
          "kind": "code",
          "note": "许可范围按实际使用的版本、路径及分发包再次核对。"
        }
      ],
      "links": [
        {
          "target": "retrieval-reranking",
          "type": "implements",
          "reason": "多阶段排序是一种实现路线"
        },
        {
          "target": "retrieval-hybrid-fusion",
          "type": "implements",
          "reason": "统一表达多路候选"
        }
      ],
      "productRoute": {
        "vendor": "Vespa",
        "category": "搜索与多阶段排序",
        "execution": "分布式匹配和多阶段排名",
        "orchestration": "schema/rank profile与应用编排",
        "context": "文本、向量和业务特征",
        "persistence": "内容索引与业务权威状态分工",
        "modelBoundary": "模型、特征和rank profile共同版本化",
        "deployment": "可采用托管形态",
        "license": "核心Apache-2.0；托管合同独立",
        "availability": "公开项目；目标部署服务资格另核查",
        "strengths": "统一表达复杂召回与排序",
        "limits": "需要搜索工程、阶段预算与运维能力"
      }
    },
    {
      "id": "knowledge-finance-as-of",
      "title": "金融数据的时点与重述",
      "aliases": [
        "point-in-time",
        "as-of",
        "restatement"
      ],
      "kind": "concept",
      "parentId": "knowledge-domain-contracts",
      "order": 120,
      "summary": "经济所属期/公开可得/接入/修正四条时间轴、实体标识、币种单位、重述链和数据许可字段。",
      "question": "如何保证历史投研只使用当时已经可得的资料？",
      "body": "### 四条时间轴决定能否用于历史判断\n\n2025年度收入可能在2026年才披露，后续报告又可能重述这个数字。经济所属期、公开可得时间、系统接入时间和修正时间不能互相代替。历史投研的资料资格应满足available_at不晚于decision_as_of，而非只看报告期是否落在过去。\n\nSEC EDGAR提供公司提交历史与XBRL事实JSON，并说明API随披露更新。它是公开申报数据的接入起点，但当前聚合结果不天然代表某个历史时点看到的版本。建议保存accession、form、原件和修正链，而不是不断用最新数字覆盖历史。\n\n### 实体和口径先于计算\n\nticker可变更或重用；发行人、法律实体、证券和上市地点应有不同标识。金额至少带币种、单位、时期、会计标签、合并范围和原始出处。相同名称的收入指标可能因税前税后、净额总额或分部口径不同而无法直接比较。\n\n对汇率换算、估值日、交易时段和行情延迟作显式选择。聚合、比率和敏感度计算交给确定性工具；模型解释所用假设和证据。不能用几段语义相关的财报片段来估计全量会计总额，再把计算包装成精确结果。\n\n### 资料可用不等于拥有全部用途\n\n研报、交易所数据、新闻和内部备忘录各有使用与再分发范围。检索约束应包含允许用户、用途、训练资格、衍生数据条款和到期时间。某个终端账号能阅读，不代表系统可以复制给全部客户或用于模型微调。\n\n验收使用重述前后、跨币种、ticker改名和报告延迟的案例，检查答案的时点、单位和许可。研究记忆可以保存方法与带日期的投资假设，但偏好高风险不构成下单授权，旧thesis也不应永久升级为公司事实。",
      "blueprint": {
        "inputs": [
          "决策时点与证券/实体ID",
          "披露原件、许可与财务口径"
        ],
        "steps": [
          "筛选当时可得版本",
          "统一单位并用确定性工具计算",
          "区分事实、假设和情景结果"
        ],
        "outputs": [
          "带as-of和来源的分析证据",
          "可复核的计算输入"
        ]
      },
      "citations": [
        {
          "url": "https://www.sec.gov/search-filings/edgar-application-programming-interfaces",
          "label": "SEC：EDGAR数据API",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "knowledge-provenance-versions",
          "type": "requires",
          "reason": "时点分析依赖不可变来源版本"
        },
        {
          "target": "retrieval-structured-queries",
          "type": "requires",
          "reason": "金额聚合交给结构化计算"
        }
      ]
    },
    {
      "id": "memory-write-scheduling",
      "title": "同步与后台记忆整理",
      "aliases": [
        "hot-path memory",
        "background consolidation",
        "sleep-time"
      ],
      "kind": "concept",
      "parentId": "memory-governance",
      "order": 120,
      "summary": "明确记住同步写、后台候选提炼、pending事件、read-your-writes和整理触发。",
      "question": "如何降低记忆写入延迟，又不让下一轮读到旧状态？",
      "body": "### 写在主路径还是后台\n\n用户明确说“以后请用中文”时，同步确认并保存可以提供可见反馈；普通长对话的经验提炼则可以后台进行，降低主响应延迟。LangChain官方区分hot-path与background写入，这两种方式的主要取舍不仅是速度，还包括一致性、可见性和任务焦点。\n\n同步写入会让模型同时处理当前任务和记忆判断，也增加工具与推理成本；后台提炼能集中整理，但用户下一次请求可能在整理完成之前到达。因此应用需要明确什么时候可以说“已经记住”，以及新Session如何看到尚未整理的最新事实。\n\n### 保留事件，允许整理落后\n\n建议先可靠记录原始事件与序号，再把整理任务放入可恢复job。活动记忆记录已处理到哪个事件；读取时可以合并少量pending事件，或对明确偏好采用同步写。不要只依靠定时摘要假设所有会话已经达到最新状态。\n\n触发可按会话结束、安静间隔、事件数量或用户显式操作选择。高频对话要去抖，避免每条消息重复整理；长时间未结束的任务也要有周期检查。后台任务必须带scope和提炼器revision，重复执行不得反复插入同一事实。\n\n### 处理在线和离线交叉更新\n\n用户纠正可能发生在旧后台job已经启动之后。提交候选时应比较事件版本和当前事实，避免旧整理结果覆盖新值；失败可以重试，但不能越过后来的撤回。并发控制与写入调度需要共同设计。\n\n验收让下一请求立刻到达、worker中断、同一job重试以及在线纠正同时发生，检查read-your-writes与活动值。分别记录前台延迟、整理滞后、失败队列和写入质量，不能把把工作移到后台直接解释为成本消失或记忆立即可用。",
      "blueprint": {
        "inputs": [
          "有序原始事件",
          "同步偏好与后台提炼规则"
        ],
        "steps": [
          "先可靠保存事件",
          "按触发条件整理并去重",
          "提交时检查新旧版本与撤回"
        ],
        "outputs": [
          "活动记忆与pending边界",
          "可恢复的后台整理进度"
        ]
      },
      "citations": [
        {
          "url": "https://docs.langchain.com/oss/python/concepts/memory",
          "label": "LangChain：Memory overview",
          "kind": "official-doc"
        },
        {
          "url": "https://www.postgresql.org/docs/current/transaction-iso.html",
          "label": "PostgreSQL：并发隔离",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "memory-concurrent-mutation",
          "type": "requires",
          "reason": "后台和在线同时写会冲突"
        }
      ]
    },
    {
      "id": "products",
      "title": "产品与技术路线",
      "en": "Products and Technical Routes",
      "aliases": [],
      "kind": "domain",
      "parentId": null,
      "order": 120,
      "summary": "按谁运行、谁持有状态、谁授权和模型边界比较真实产品。",
      "question": "怎样按技术路线和控制边界比较产品与技术路线？",
      "body": "产品比较应先分层。代码Harness、应用内runtime、托管Agent平台和持续个人Agent解决不同问题，不能仅按功能数量排榜。公开源码可以审查可见实现，官方使用文档可以确认产品合同，厂商架构说明则仍需目标环境验证。\n\n本分支以2026-10-15为观察基线，逐页说明执行、编排、context、持久化、模型替换、部署、许可和可用性。版本与渠道分别记录；SDK、个人产品和模型API不混为一类。没有公开的内部数据库、调度器或system prompt，明确保留未知。\n\n采用方式优先考虑配置与接口集成，再比较修改源码的必要性。企业可自建身份、Task、证据、工具网关和评测，复用一个主要runtime；不必fork完整coding-agent再重写多租户平台。\n\n[OpenAI：Agent运行时选择](https://developers.openai.com/api/docs/guides/agents)；[Claude Agent SDK：概览](https://code.claude.com/docs/en/agent-sdk/overview)；[Pydantic AI：Harness能力边界](https://pydantic.dev/docs/ai/harness/)。",
      "blueprint": {
        "inputs": [
          "业务场景与部署偏好",
          "公开产品与源码证据",
          "权限、状态和退出要求"
        ],
        "steps": [
          "辨别产品层次",
          "比较固定技术维度",
          "验证实际账号与任务",
          "确定集成或观察边界"
        ],
        "outputs": [
          "可比较产品路线",
          "采用及未知事项",
          "有证据的技术选择"
        ]
      },
      "citations": [
        {
          "url": "https://developers.openai.com/api/docs/guides/agents",
          "label": "OpenAI：Agent运行时选择",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://code.claude.com/docs/en/agent-sdk/overview",
          "label": "Claude Agent SDK：概览",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        },
        {
          "url": "https://pydantic.dev/docs/ai/harness/",
          "label": "Pydantic AI：Harness能力边界",
          "kind": "official-doc",
          "note": "观察基线：2026-10-15。固定SHA代码用于说明可见实现；产品声明不等同目标环境实测。"
        }
      ],
      "links": []
    },
    {
      "id": "retrieval-contextual-enrichment",
      "title": "分块上下文增强",
      "aliases": [
        "contextual retrieval",
        "context enrichment"
      ],
      "kind": "concept",
      "parentId": "retrieval-representation",
      "order": 120,
      "summary": "标题路径与生成context enrichment、embedding/BM25双侧增强、派生文本标识和消融。",
      "question": "孤立片段如何携带它在全文中的位置和背景？",
      "body": "### 为片段补上它属于什么\n\n某个chunk只写“增长了12%”，即使切块过程没有丢字，仍缺少主体、期间和指标。Context enrichment在索引前给片段补充简短背景，例如公司、财年和章节主题，使检索更容易把自然问题与孤立片段对应起来。确定性标题路径与模型生成解释是两种不同来源，应分别记录。\n\nAnthropic于2024年提出Contextual Retrieval，把文档内解释加入embedding与BM25输入，并与重排组合评估。其公开实验是特定数据上的作者结果，不能直接外推为企业的固定改进比例；需要自己的切块、模型和query做消融。\n\n### 增强内容不是新的权威事实\n\n建议保留原始chunk、补充背景、生成器版本和输入文档版本，检索可以使用合并文本，回答事实仍引用原件。生成解释若误认主体或时间，可能系统性地把chunk放到错误位置，因此增强阶段也应检查实体、日期、单位和与原文冲突。\n\n对于结构清晰的制度文档，标题、章节路径和少量元数据可能已足够；对大量跨页、指代或重复段落的资料，模型背景解释才更可能有增益。不要每个chunk都生成长摘要，额外token会提高入库成本，也可能放大猜测内容。\n\n### 用反例衡量收益\n\n比较原chunk、加入确定性路径、加入生成context及二者组合，固定召回和重排预算。除了Recall，还检查错误实体命中率、时间误归属、重复证据和最终答案支持度。正确段落被召回但生成背景不正确，也应算增强质量缺陷。\n\n更新文档后，背景文本必须随依赖版本失效；只重算正文向量而保留旧解释，会把两版语义拼接。一个有用的验收样本是两家主体使用相同指标的段落，确认增强让系统更好区分它们，而不是把错误公司名写进所有片段。",
      "blueprint": {
        "inputs": [
          "原chunk与完整文档范围",
          "标题路径与生成器版本"
        ],
        "steps": [
          "优先加入确定性背景",
          "按需生成简短文档内解释",
          "校验派生背景并做消融"
        ],
        "outputs": [
          "带来源的增强索引文本",
          "仍可独立引用的原chunk"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/contextual-retrieval",
          "label": "Anthropic：Contextual Retrieval",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "retrieval-chunking",
          "type": "requires",
          "reason": "需要确定chunk和文档关系"
        },
        {
          "target": "knowledge-provenance-versions",
          "type": "requires",
          "reason": "增强文本应保留派生血缘"
        }
      ]
    },
    {
      "id": "storage-object-artifacts",
      "title": "对象原件与长输出存储",
      "aliases": [
        "object storage",
        "artifact",
        "content-addressed"
      ],
      "kind": "concept",
      "parentId": "storage-architecture",
      "order": 120,
      "summary": "原件/解析JSON/图像/artifact/录制保存、内容寻址、版本与授权读取。",
      "question": "为什么原始文件、长工具输出和模型上下文应分开保存？",
      "body": "### 长内容保留原件，用引用进入执行\n\nPDF、页面图像、解析JSON、音视频、长工具输出和最终报告不适合全部塞进关系行或模型历史。对象存储可以保存这些大内容，关系库记录其身份、版本、权限、状态与hash，Agent通过受控fetch按需读取。引用能缩小上下文，也保留独立恢复与审计入口。\n\nS3 Versioning官方资料说明可为对象保存多个版本。它提供底层版本机制，却不自动定义“哪一版制度当前有效”、某用户可读什么、或派生摘要依赖哪个版本；这些仍需应用数据合同。可变对象key与业务版本也不应混为一个概念。\n\n### 原始、派生、最终产物分开\n\n建议区分raw、parsed、evidence和artifact类别，每项记录内容类型、大小、生成器、来源版本和保留规则。模型生成文件与用户上传原件可能具有不同信任级别；未知类型先隔离，下载和解析经过类型、大小及安全检查。\n\n内容寻址可以减少重复存储，但不能让两个租户因为hash相同就共享访问权。预签名URL应有有限范围和有效期；长期任务保存稳定对象身份，不把短时URL当唯一恢复指针。引用展开时应重新授权，避免旧链接绕过资料撤回。\n\n### 删除和恢复需要同时设计\n\n版本化可能意味着删除活动版本并未物理删除历史版本。生命周期规则、保留锁、备份和派生物清理必须按实际合同配置；只删除关系行会留下孤立大文件，只删除对象又可能留下可被继续引用的元数据。\n\n验收包括对象损坏hash、链接过期、旧版本读取、权限变化和恢复重放。长输出可被模型概述，但概述不能成为唯一记录；需要精确核验时，系统必须能够取回对应原件。完成任务的回执应引用可读、可验证的artifact，而非仅声称“已生成”。",
      "blueprint": {
        "inputs": [
          "大文件与长输出",
          "对象身份、版本和权限"
        ],
        "steps": [
          "保存原始与派生对象",
          "在关系状态中登记稳定引用",
          "按需授权读取并执行保留清理"
        ],
        "outputs": [
          "可恢复原件与artifact",
          "受控而非无限暴露的内容入口"
        ]
      },
      "citations": [
        {
          "url": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html",
          "label": "Amazon S3：对象版本管理",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "knowledge-legal-validity",
      "title": "法律资料的法域与效力",
      "aliases": [
        "jurisdiction",
        "effective date",
        "citator",
        "matter isolation"
      ],
      "kind": "concept",
      "parentId": "knowledge-domain-contracts",
      "order": 130,
      "summary": "jurisdiction、authority type、公布/生效/废止、case treatment、matter隔离和引用实体。",
      "question": "如何检索适用地区、日期和权威层级正确的法律资料？",
      "body": "### 相关判例不一定适用\n\n法律检索至少同时受法域、时间和权威层级约束。一段论述语义上与问题高度相似，可能来自别的地区、已经废止的法条、非正式解释或不同程序阶段。将这些条件只写在最终提示词里，无法修复召回阶段已经混入的错误资料集合。\n\n建议为法规保存公布、生效、修订和废止时间，为案例保存法院、citation、程序状态与后续处理信息；合同则明确草稿、签署、修订和终止版本。每项效力判断必须有来源和复核时间，不能把检索分数或“Published”标签当作现行有效的证明。\n\n### 覆盖范围必须可见\n\nCourtListener当前v4搜索支持关键词与语义检索，官方说明默认仅返回published opinions，其他status需显式请求。这说明某个接口的默认结果不是法律资料的完整全集。数据覆盖、缺失文本、更新延迟与状态过滤应在产品合同中说明。\n\n引用核验应分层：实体是否存在，原文是否包含被引用命题，地域和日期是否适用，是否具有可靠的后续效力信息。若系统没有citator或权威状态来源，就应标明无法完成该项验证；模型对旧案例的熟悉不能补上这一数据能力。\n\n### 客户事项是隔离边界\n\n客户文档、聊天、工具输出、摘要、检索缓存和长期记忆都应带matter范围。团队可共享抽象审阅runbook，但某事项中的事实和策略不能自动进入全所通用记忆。将客户名称去掉也未必消除可识别信息，应按实际资料合同决定共享资格。\n\n验收应覆盖同名法条不同版本、相似判例不同法域、真实但不支持论点的citation以及已撤回事项权限。成功标准是提供适用证据并识别未知边界，而不是生成看起来专业且引用很多的文书。",
      "blueprint": {
        "inputs": [
          "法域、问题日期与事项权限",
          "法规/案例/合同版本及效力来源"
        ],
        "steps": [
          "限定资料域与时间",
          "核验citation、命题和效力状态",
          "交付可追溯结论及未验证项"
        ],
        "outputs": [
          "适用范围明确的法律证据",
          "事项隔离的引用记录"
        ]
      },
      "citations": [
        {
          "url": "https://wiki.free.law/c/courtlistener/help/api/rest/v4/search",
          "label": "CourtListener：Legal Search API",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "knowledge-provenance-versions",
          "type": "requires",
          "reason": "法律版本与效力要可追溯"
        },
        {
          "target": "retrieval-evidence-assembly",
          "type": "controls",
          "reason": "证据组装必须保留法域日期"
        }
      ]
    },
    {
      "id": "memory-scope-isolation",
      "title": "记忆命名空间与共享",
      "aliases": [
        "memory namespace",
        "shared memory",
        "tenant isolation"
      ],
      "kind": "concept",
      "parentId": "memory-governance",
      "order": 130,
      "summary": "tenant/user/team/task/matter作用域、来源权限继承、共享只读与检索钉死身份。",
      "question": "个人、团队、客户事项与任务记忆如何共享而不串线？",
      "body": "### 相同事实在不同主体下有不同资格\n\n个人偏好、团队约定、任务笔记和客户事项事实需要不同namespace。一个Agent能够同时访问多个范围，不意味着它可以把读到的内容合并成全局记忆。Scope应来自服务端已验证身份与任务合同，不能让模型随意填写其他用户或tenant ID。\n\nLangChain长期store支持自定义namespace，Zep v4则把user context graph和thread分开。框架提供组织容器，但资料是否可共享、是否继承原权限、何时撤回，仍需应用定义。Namespace只是实现边界的一部分，不是自动正确的授权模型。\n\n### 共享必须说明方向\n\n团队可维护只读政策块，成员可以读取；个人偏好通常不应反向提升为团队规则。客户事项中的经验可以提出脱敏程序候选，却不应把客户事实复制到全所公共记忆。子Agent的结果也必须保留来源scope，不能因为回到主Agent就扩大可见范围。\n\n建议memory item同时保存owner、scope类型、scope ID、来源授权与当前状态。跨scope搜索只能由预先允许的范围集合构成，并在返回、注入上下文和交付时检查。共享摘要的权限不能宽于其依赖资料。\n\n### 权限变化会影响旧记忆\n\n用户离开团队、案件归档或源文档变私有后，过去抽取的事实也可能失去使用资格。记忆缓存、常驻profile和已恢复checkpoint要识别当前授权，而不是沿用写入时的许可。保留历史审计与允许在线回忆是两个不同用途。\n\n验收使用两个tenant、相似姓名、相同问题和部分共享资料，检查搜索结果、模型输入、常驻块、引用与导出。再降级权限并重复查询，确认旧memory不绕过限制。没有发生可见泄漏的少量样本不能证明理论无漏洞，应报告覆盖范围和样本量。",
      "blueprint": {
        "inputs": [
          "服务端身份与任务范围",
          "记忆owner及来源授权"
        ],
        "steps": [
          "固定可搜索namespace集合",
          "对共享方向与派生权限作检查",
          "撤回后复核常驻与检索记忆"
        ],
        "outputs": [
          "当前可用记忆集合",
          "跨scope访问审计"
        ]
      },
      "citations": [
        {
          "url": "https://docs.langchain.com/oss/python/concepts/memory",
          "label": "LangChain：Memory overview",
          "kind": "official-doc"
        },
        {
          "url": "https://help.getzep.com/v4/memory-security",
          "label": "Zep v4：Memory security",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "knowledge-acl-propagation",
          "type": "requires",
          "reason": "派生记忆继承来源可见性"
        },
        {
          "target": "memory-recall-policy",
          "type": "controls",
          "reason": "查询不能任意指定其他主体"
        }
      ]
    },
    {
      "id": "retrieval-filtered-ann",
      "title": "权限过滤与ANN召回",
      "aliases": [
        "filtered ANN",
        "pre-filter",
        "post-filter",
        "HNSW"
      ],
      "kind": "concept",
      "parentId": "retrieval-reliability",
      "order": 130,
      "summary": "pre/post/in-filter差别、选择率与语义相关性、迭代扫描、exact子集基线。",
      "question": "为什么加了tenant或ACL过滤后会找不满top-k？",
      "body": "### 过滤改变了正确答案的集合\n\n企业查询通常带tenant、部门、客户事项、日期和资料类型约束。ANN应寻找授权子集内的最近邻，而不是先找全库最近邻再删除不可见结果。后者可能让top-k不足，甚至把真正相关但不在全库前列的授权资料完全漏掉。\n\npgvector官方说明近似索引扫描之后应用过滤可能减少结果，并提供iterative scans继续扫描直到达到条件或上限。Qdrant、Milvus、Elastic和Weaviate采用不同过滤与搜索机制，不能仅根据都支持HNSW就认为过滤质量相同。\n\n### 小集合未必该走近似搜索\n\n过滤可能留下全库10%、1%或极少资料。条件还可能与语义分布相关或反相关，多个AND过滤会进一步改变图的可达性。对非常小的授权子集，exact scan可能更简单；对大集合则需要近似索引和适当搜索参数。具体切换由实际数据与执行计划决定。\n\n基准真值应在授权子集内计算exact kNN，再与近似结果比较；这衡量索引近似误差，与人工标注的语义相关性Recall是两个指标。即使近似召回完美，embedding仍可能认为错误资料最相近，不能把两种质量混成一个分数。\n\n### 同时验证隔离与尾延迟\n\n按选择率、tenant规模、冷暖缓存和更新并发分桶，记录实际返回数量、exact overlap、p95以及扫描工作量。共享索引中一个热租户可能影响其他租户性能，分区可以改善隔离，却增加分区管理与跨域检索成本。\n\n验收不能通过取消过滤来达到延迟目标。若预算不足，应缩小范围、采用经过验证的exact策略或说明证据不足。返回得快且结果数量够，不等于找到了正确授权证据；安全和检索质量都要独立检查。",
      "blueprint": {
        "inputs": [
          "query向量",
          "当前授权过滤与索引配置"
        ],
        "steps": [
          "计算授权子集exact基线",
          "按选择率测试ANN策略",
          "检查召回、结果数与尾延迟"
        ],
        "outputs": [
          "过滤后候选集合",
          "近似误差与隔离诊断"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/pgvector/pgvector",
          "label": "pgvector：Filtering与Iterative Index Scans",
          "kind": "code"
        },
        {
          "url": "https://milvus.io/docs/filtered-search.md",
          "label": "Milvus：Filtered search",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "eval-rag-quality",
          "type": "requires",
          "reason": "授权子集exact kNN定义基准"
        }
      ]
    },
    {
      "id": "storage-redis-ephemeral",
      "title": "缓存与临时协调状态",
      "aliases": [
        "Redis",
        "ephemeral state",
        "cache"
      ],
      "kind": "concept",
      "parentId": "storage-architecture",
      "order": 130,
      "summary": "查询缓存/短锁/限流/队列辅助与权威持久化边界、恢复合同。",
      "question": "哪些状态可以丢失，哪些不能只放在缓存里？",
      "body": "### 快速状态先判断能否丢失\n\n查询缓存、限流计数、短期协调和会话加速适合使用低延迟内存服务，但任务是否完成、审批是否发生、外部操作是否成功，不应仅保存在可能被逐出的缓存项里。选择Redis类服务前，先为每个键定义丢失后如何重建，以及是否影响业务正确性。\n\nRedis官方持久化文档区分RDB、AOF、无持久化及组合策略，各自有性能、恢复与数据丢失窗口。启用一种持久化选项并不自动等于满足任务权威状态合同；托管复制也不能代替明确的恢复目标和备份演练。\n\n### 缓存值不拥有授权\n\n检索与答案缓存需要绑定tenant、当前可见范围、ACL revision、资料generation及模型/检索版本。命中后仍可能需要复核授权与新鲜度。缓存相似问题尤其要保留地区、日期、事项和单位条件，不能因为语义接近就复用另一用户结果。\n\n短锁只约束某个时间窗口内的并发，不应成为“外部操作绝不会重复”的证明。长任务可能超过租期、worker可能暂停，结果未知时仍需权威幂等记录和外部读回。队列辅助状态也应区分已投递、已消费和业务操作已验证。\n\n### 设计可退化路径\n\n缓存不可用时，应能从权威库读取或受控排队，避免缓存故障放大成权限绕过。对高并发热键使用去重与并发限制，防止缓存同时过期触发大量相同下游调用。关键结果先可靠落库，再更新可丢失加速层。\n\n验收包括逐出、重启、复制切换、锁超时和大批缓存失效，分别报告业务正确性与延迟。更高命中率不能补偿过期政策或跨租户泄漏；若恢复后找不到唯一任务状态，说明缓存已经承担了未经设计的权威职责。",
      "blueprint": {
        "inputs": [
          "可重建的缓存与协调需求",
          "恢复目标及键作用域"
        ],
        "steps": [
          "明确每类键的丢失语义",
          "配置持久化与失效合同",
          "验证逐出和故障降级"
        ],
        "outputs": [
          "低延迟加速层",
          "不依赖缓存存活的业务状态"
        ]
      },
      "citations": [
        {
          "url": "https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/",
          "label": "Redis：Persistence",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "storage-authority-derived",
          "type": "complements",
          "reason": "可丢失缓存不是权威状态"
        }
      ]
    },
    {
      "id": "talks",
      "title": "工程讲座与实践观点",
      "aliases": [
        "talks"
      ],
      "kind": "domain",
      "parentId": null,
      "order": 130,
      "summary": "从一手文稿理解Harness、反馈与Eval，保留讲者主张和验证边界。",
      "question": "这场讲座提出什么机制，哪些结论可迁移到企业设计？",
      "body": "实践讲座提供团队如何界定问题、设计接口和组织反馈的第一手观点，但它与产品文档、独立实验和生产效果证据属于不同层次。本分支围绕机制及工程含义组织阅读，而非罗列产品宣传与最新功能。\n\n四个叶页分别讨论生产harness可靠性、Agent接口和持久上下文演进、可检查目标与并行编码，以及数据和评分如何支持产品决策。每页标记原发布方逐字稿、时间定位、历史背景和可迁移验收问题，具体产品的现行可用性另查产品分支。\n\n完整文稿阅读不等于连续观看视频，厂商内测不等于独立复现，演示完成也不等于长期生产可靠。将观点转成自己的任务、故障注入和验收证据，才有助于方案选择；无法核实的日期或产品状态不应从讲座标题推断。",
      "blueprint": {
        "inputs": [
          "原始讲座文稿",
          "待设计的企业任务"
        ],
        "steps": [
          "区分讲者主张与证据",
          "抽取可迁移机制",
          "形成可执行验证"
        ],
        "outputs": [
          "设计问题与验收项",
          "证据及适用边界"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Agent评测方法背景",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "knowledge-education-state-contract",
      "title": "教学知识与学生状态合同",
      "aliases": [
        "knowledge tracing",
        "student model",
        "mastery estimate"
      ],
      "kind": "concept",
      "parentId": "knowledge-domain-contracts",
      "order": 140,
      "summary": "课程版本/知识点/题目rubric与作答证据、mastery估计/不确定度/教师覆盖分开建模。",
      "question": "如何把教材事实与对学生掌握程度的估计分开？",
      "body": "### 教材事实与学生估计是不同对象\n\n教学知识库保存课程版本、学习目标、知识点、先修关系、题目、答案和评分rubric；学生状态保存实际作答、提示次数、错误模式与复习记录。前者描述教学内容，后者只是对当前掌握程度的估计。学生一次答错不应改写教材，也不应产生永久的能力标签。\n\n建议把掌握估计连接到明确证据：concept ID、attempt IDs、估计器版本、不确定度、最后练习时间和教师覆盖。学生猜对、得到提示后答对和独立迁移成功应形成不同证据，不能都压成同一个正确率或“已掌握”。\n\n### 状态随证据更新\n\n某一轮的提示内容属于session/task上下文；跨会话需要保留的是可复核表现与有限认知状态。新证据可能推翻旧判断，教师也应能修正模型估计。情绪、疾病或家庭情况等敏感结论不能从语气猜测后自动长期保存。\n\n课程、题目和模型评分rubric需要版本化，否则同一学生的成绩可能是在不同标准下取得。若更换评估器，保留原始作答以便重评，并记录哪一部分变化来自学生学习，哪一部分来自评分系统改变。\n\n### 云优先仍需限制数据用途\n\n美国教育部提供面向教育科技服务商和在线服务的学生隐私资料；实际适用要求须按地区、学校和年龄场景确定。工程上应明确学生、班级、学校、教师和家长的访问范围，收集必要字段，并让训练使用成为独立的数据资格判断。\n\n验收不仅检查回答是否正确，还要测试学生能否在无提示、延迟后的新题中迁移。验证学生状态库时，重点看证据关联、错误纠正、教师覆盖和跨学生隔离；教学效果指标与记忆完整性分别统计，避免把代做答案当成学习进展。",
      "blueprint": {
        "inputs": [
          "课程/题目版本",
          "学生作答、提示与教师反馈"
        ],
        "steps": [
          "保存原始尝试及评分标准",
          "更新带不确定度的掌握估计",
          "按角色授权并用迁移表现复核"
        ],
        "outputs": [
          "可更正的学生状态",
          "与教学知识分离的认知证据"
        ]
      },
      "citations": [
        {
          "url": "https://studentprivacy.ed.gov/privacy-and-education-technology",
          "label": "美国教育部：Privacy and Education Technology",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "memory-semantic-facts",
          "type": "complements",
          "reason": "掌握估计不是永久事实标签"
        },
        {
          "target": "memory-temporal-conflicts",
          "type": "requires",
          "reason": "学生状态随新证据更新"
        }
      ]
    },
    {
      "id": "memory-temporal-conflicts",
      "title": "时间事实与冲突更新",
      "aliases": [
        "bitemporal memory",
        "supersedes",
        "knowledge update"
      ],
      "kind": "concept",
      "parentId": "memory-governance",
      "order": 140,
      "summary": "valid_from/to与recorded_at、correction/supersedes、临时偏好、现实变化与错误纠正。",
      "question": "两条记忆互相矛盾时，应覆盖、并存还是标记失效？",
      "body": "### 变化与错误不是同一种冲突\n\n“张三是项目负责人”去年正确，今年换成李四；“张三其实从未负责”则是纠错。前者要求保留历史有效区间，后者要求撤销错误事实。简单用最新记录覆盖旧值，会丢失时间推理；简单并存又可能让模型同时采用矛盾信息。\n\n建议区分valid_from与valid_to表示现实有效时间，recorded_at表示系统何时获知，并保存correction或supersedes关系。Graphiti的时间图路线展示随episode更新事实关系的机制，可作为实现候选，但业务仍需定义什么证据足以改写某类事实。\n\n### 临时条件不能被永久化\n\n“这周不喝咖啡”不是长期饮食偏好，“这次先不做回测”不是所有投资研究的规则。抽取时应保留条件、时间与说话者；无法判断有效期时宁可标记待复核，而不默认无限期生效。用户明确纠正一般应优先于模型旧推断。\n\n同一主体、属性和值相近的事实可以进入冲突候选集，但不能仅靠向量相似度自动合并。公司、证券、同名学生和客户事项需要稳定实体键。来自不同权威层级的矛盾还需保留来源，让应用按资料合同裁决。\n\n### 按问题时间读取\n\n查询“现在负责人是谁”应使用当前有效事实；查询“上季度由谁审批”应读取相应时间区间。系统接入较晚时还要避免假装当时已经知道。金融as-of和法律生效是这一原则在专业资料上的独立数据合同。\n\n验收包含先后变化、晚到事件、反向纠错、重叠有效期、临时偏好和来源撤回。检查写入后的活动值、历史回答、冲突提示与依赖记忆是否一起更新。成功不是没有矛盾记录，而是矛盾可见、时间语义明确且不会错误用于当前任务。",
      "blueprint": {
        "inputs": [
          "新旧事实与稳定主体",
          "有效时间、观察时间和来源"
        ],
        "steps": [
          "分类变化或纠错",
          "建立有效区间与替代关系",
          "按as-of选取并显示未决冲突"
        ],
        "outputs": [
          "可追踪事实历史",
          "当前有效值及冲突状态"
        ]
      },
      "citations": [
        {
          "url": "https://help.getzep.com/graphiti/getting-started/welcome",
          "label": "Graphiti：时间上下文图",
          "kind": "official-doc"
        },
        {
          "url": "https://arxiv.org/abs/2501.13956",
          "label": "Zep：Temporal Knowledge Graph Architecture",
          "kind": "paper"
        }
      ],
      "links": [
        {
          "target": "knowledge-finance-as-of",
          "type": "complements",
          "reason": "金融时点是时间语义专门应用"
        },
        {
          "target": "knowledge-education-state-contract",
          "type": "feeds",
          "reason": "认知状态随证据改变"
        },
        {
          "target": "memory-forgetting",
          "type": "feeds",
          "reason": "被替代不一定等于物理删除"
        }
      ]
    },
    {
      "id": "retrieval-graph-rag",
      "title": "实体图与GraphRAG",
      "aliases": [
        "GraphRAG",
        "knowledge graph",
        "DRIFT"
      ],
      "kind": "concept",
      "parentId": "retrieval-strategies",
      "order": 140,
      "summary": "local/global/DRIFT、实体消歧、关系来源、图更新与摘要ACL。",
      "question": "什么问题值得为关系图和社区摘要付出额外成本？",
      "body": "### 图适合关系问题与全局综合\n\n“某项目涉及哪些部门和供应商”需要追踪实体关系，“全部访谈最主要的主题是什么”需要跨资料综合；普通top-k语义搜索不一定能覆盖这些问题。GraphRAG通过抽取实体、关系和社区结构，为局部关系查询或全局主题总结提供另一种索引。\n\nMicrosoft GraphRAG官方区分local、global、DRIFT和basic search：局部检索结合图与原文，全局查询使用社区报告，DRIFT结合局部与社区信息。官方也指出global search资源消耗较大。因此图路线应服务明确问题，不必替换每次简单政策检索。\n\n### 图里的边仍需要证据\n\n实体消歧、关系方向、否定、时间和条件会影响图质量。模型抽取的“合作”不能自动升级为采购关系，旧关系也不能永久生效。建议每条边保存来源片段、抽取版本、有效时间与验证状态，并允许回到原文检查。\n\n社区摘要如果合并多个权限域，可能通过综合结果泄露受限关系。应限制聚类与摘要的可见范围，或建立可证明的授权投影；不能只给底层chunk加ACL，而让全库社区报告对所有人开放。资料删除后，派生图和摘要也需更新。\n\n### 用失败集决定是否投资\n\n先确认已有解析、混合召回和重排仍无法解决的案例确实需要关系遍历或全局覆盖。比较基本RAG、图局部检索和全局总结的质量、token成本、延迟及增量更新成本。图可提高某类能力，也可能把抽取错误扩散到更多答案。\n\n验收应包括同名实体、关系变更、被撤回来源和跨权限社区。答案不仅要列出关系，还要说明证据、日期和未知部分。GraphRAG是文档检索策略，不能因为同样使用图就与用户长期记忆或业务权威图谱混为一谈。",
      "blueprint": {
        "inputs": [
          "有来源和权限的资料",
          "实体及关系问题"
        ],
        "steps": [
          "抽取并消歧实体关系",
          "建立社区与来源索引",
          "按问题选择local/global/DRIFT"
        ],
        "outputs": [
          "图与原文联合证据",
          "有成本边界的全局综合"
        ]
      },
      "citations": [
        {
          "url": "https://microsoft.github.io/graphrag/query/overview/",
          "label": "Microsoft GraphRAG：查询模式",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "knowledge-provenance-versions",
          "type": "requires",
          "reason": "每条抽取边追到原文"
        },
        {
          "target": "memory-temporal-conflicts",
          "type": "complements",
          "reason": "文档GraphRAG与时间记忆有不同任务"
        }
      ]
    },
    {
      "id": "security",
      "title": "权限、安全与数据治理",
      "parentId": null,
      "kind": "domain",
      "order": 140,
      "en": null,
      "aliases": [],
      "summary": "将授权、信任和数据生命周期放在模型之外执行。",
      "question": "Agent 能看到什么、能改变什么，谁来保证？",
      "body": "## 安全是贯穿系统的约束\n攻击者可能控制输入、网页、上传文件、工具返回、仓库依赖和记忆候选。企业风险包括越权读、凭证泄漏、重复副作用和错误发布。提示词可以提醒模型识别风险，但真正边界来自身份、能力授权、隔离和外部状态核验。\n\n本分支负责统一威胁与治理语义。工具页展开调用机制，知识页展开文档ACL，memory页展开记忆作用域，评测页展开红队；这些页面引用这里的原则。安全测试还需保持合法任务完成率，避免用全面拒绝伪装安全。\n\n云端优先不等于忽略数据合同。模型推理、会话、文件、日志、备份与训练导出分别核对权限、保留、地区与删除。处理高影响领域时按具体业务实体、法域和用途落实专业审查，不能把通用架构图当作合规证明。",
      "blueprint": {
        "inputs": [
          "身份",
          "数据分类",
          "动作风险"
        ],
        "steps": [
          "限制能力",
          "隔离不可信输入",
          "审计与撤销"
        ],
        "outputs": [
          "受控执行",
          "可追溯责任"
        ]
      },
      "citations": [
        {
          "url": "https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices",
          "label": "MCP：Security best practices",
          "kind": "official-doc"
        },
        {
          "url": "https://developers.openai.com/api/docs/guides/your-data",
          "label": "OpenAI：API data controls",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "storage-outbox-consistency",
      "title": "Outbox与跨库一致性",
      "aliases": [
        "outbox",
        "CDC",
        "eventual consistency"
      ],
      "kind": "concept",
      "parentId": "storage-architecture",
      "order": 140,
      "summary": "权威事务+outbox、消费幂等、索引generation、待同步/失败/重放、撤回优先。",
      "question": "事务库更新了，向量库没更新，系统如何发现并补齐？",
      "body": "### 双写中间总有一个失败窗口\n\n关系库更新文档状态之后，向量服务可能超时；先写向量再写关系库，也可能留下没有权威身份的孤立索引。两个系统各自成功的接口并不提供跨系统事务。需要明确哪个系统权威、事件如何传播、消费者如何处理重复，以及怎样发现持续落后的索引。\n\nAWS公开的transactional outbox模式把业务变更和待发送消息写入同一事务，后续由发布者转发事件。这样数据库提交与待发布记录一起存在，但消费者仍须幂等，事件也不天然保证所有下游按相同顺序完成。\n\n### 用对象版本拒绝旧事件\n\n建议事件包含event ID、source object、期望版本、操作类型和generation。消费者写入前比较当前期望状态，避免乱序的旧更新覆盖新版本。完成后记录实际索引版本和处理结果；失败事件进入可观察重试队列，而不是无限静默重试。\n\n删除与权限撤回宜先在权威层禁用，异步消费负责清理。若允许较旧内容继续服务，应明确只针对普通内容更新，并给出新鲜度；不能把同一最终一致窗口扩展到敏感权限。读取服务需要能拦截尚未传播的撤回。\n\n### 对账是机制的一部分\n\n逐对象比较权威版本和检索generation，检查缺chunk、旧chunk、孤立向量与漏删除。系统应知道每个索引当前落后多久、哪些对象失败，以及重放从何处继续。只监控消息队列长度不足以证明索引内容正确。\n\n验收主动制造提交后崩溃、发布后未确认、重复消费、乱序、外部服务失败与索引全量重建。正确结果不是事件只出现一次，而是重复与恢复不会改变最终合法状态。任务checkpoint可以记录传播进度，但不能替代实际下游读回与对账。",
      "blueprint": {
        "inputs": [
          "权威事务与对象版本",
          "待同步事件及目标索引"
        ],
        "steps": [
          "事务内写状态和outbox",
          "幂等消费并拒绝旧版本覆盖",
          "对账期望与实际generation"
        ],
        "outputs": [
          "可重放的一致性链",
          "可观察的落后与异常对象"
        ]
      },
      "citations": [
        {
          "url": "https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html",
          "label": "AWS：Transactional outbox pattern",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "knowledge-incremental-publishing",
          "type": "implements",
          "reason": "跨库同步需outbox与重放"
        },
        {
          "target": "knowledge-deletion-lineage",
          "type": "complements",
          "reason": "删除重放贯穿派生层"
        }
      ]
    },
    {
      "id": "memory-forgetting",
      "title": "过期、撤回与遗忘",
      "aliases": [
        "forgetting",
        "memory TTL",
        "memory deletion"
      ],
      "kind": "concept",
      "parentId": "memory-governance",
      "order": 150,
      "summary": "TTL复核、撤回即时禁用、低价值合并、归档、派生摘要/向量/skill血缘。",
      "question": "哪些记忆该过期，用户删除后怎样真正生效？",
      "body": "### 遗忘不只有一个删除按钮\n\n长期memory需要区分到期复核、失去活动价值、明确撤回、错误纠正和物理删除。旧项目经验可以归档，临时偏好应到期，错误事实应停止使用，敏感资料可能还要清理派生物。不能用一个相似度阈值统一决定这些不同操作。\n\nMem0官方删除操作资料展示按记忆ID或范围进行删除的接口。接口存在只证明服务提供操作，不证明应用已经清除自己维护的profile、摘要、缓存或生成skill。全链路遗忘需要来源lineage与实际消费方清单。\n\n### 先停止使用，再完成清理\n\n用户撤回后，活动召回和常驻块应立即禁用相关项；随后处理embedding、图边、摘要和导出。保留最小操作回执以证明发生过删除，不应在回执里再次复制待删正文。来源文件被撤回时，由其派生的记忆也要重新判断资格。\n\nTTL到期可以触发复核而非直接判假；低频但关键的偏好可能仍有价值，经常被访问的错误事实反而应删。访问频率只是一个信号，不能替代事实权威、保留合同和用户意愿。\n\n### 备份与恢复也在边界内\n\n归档审计与活动memory分开授权；备份保留多久、恢复后如何重放撤回，需有明确合同。只删除当前索引，再从原事件重新提炼，可能把同一错误重新写回，因此撤回事件本身也要被后续整理器识别。\n\n验收先让一条事实进入profile、向量、摘要和后续任务，再撤回并检查所有读取入口；模拟后台job晚到和备份恢复，确保旧内容不复活。指标应包含撤回生效延迟、派生清理完成率与误删，而非只报告API返回成功。",
      "blueprint": {
        "inputs": [
          "撤回、过期或纠错事件",
          "memory及派生来源链"
        ],
        "steps": [
          "禁用活动使用",
          "按类型归档、复核或物理清理",
          "恢复与重提炼时重放撤回"
        ],
        "outputs": [
          "不再被使用的旧记忆",
          "可核验的清理进度"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/mem0ai/mem0/blob/main/docs/core-concepts/memory-operations/delete.mdx",
          "label": "Mem0：Delete memory",
          "kind": "code"
        },
        {
          "url": "https://help.getzep.com/v4/memory-security",
          "label": "Zep v4：Memory security",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "knowledge-deletion-lineage",
          "type": "requires",
          "reason": "使用统一派生清理能力"
        }
      ]
    },
    {
      "id": "operations",
      "title": "实施、观测与可靠性",
      "parentId": null,
      "kind": "domain",
      "order": 150,
      "en": null,
      "aliases": [],
      "summary": "从最简基线逐步扩展，以任务结果和错误预算管理系统。",
      "question": "怎样知道系统值得上线、值得继续优化？",
      "body": "## 按可验证能力分阶段\n先确定任务与数据资格，再实现可重复的只读基线，然后加入恢复与副作用，最后按瓶颈扩展多Agent、专用检索和训练。阶段由验收条件定义，不按固定周数承诺；数据清理、专家标注、采购和工程分别估算。\n\n观测必须把任务结果、执行可靠性与模型质量连起来。健康检查正常不意味着检索新鲜、供应商可用或产物正确。每个有效结果成本要包含失败尝试与人工复核。\n\n运行中积累的是可解释的证据和改进候选；真正的能力发布仍经过评测、灰度与回滚。这个分支管理交付运营，evaluation管理证据强度，learning管理变更手段。",
      "blueprint": {
        "inputs": [
          "业务目标",
          "运行指标"
        ],
        "steps": [
          "建立基线",
          "定位瓶颈",
          "受控扩展"
        ],
        "outputs": [
          "运营SLO",
          "版本化改进"
        ]
      },
      "citations": [
        {
          "url": "https://github.com/open-telemetry/semantic-conventions-genai",
          "label": "OpenTelemetry：GenAI semantic conventions",
          "kind": "code"
        },
        {
          "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
          "label": "Anthropic：Demystifying evals for AI agents",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "incident-recovery-runbooks",
          "type": "complements",
          "reason": "SLO和观测发现异常后需要可执行的止损与恢复动作。"
        }
      ]
    },
    {
      "id": "retrieval-structured-queries",
      "title": "结构化查询与指标层",
      "aliases": [
        "text-to-SQL",
        "metrics layer",
        "确定性计算"
      ],
      "kind": "concept",
      "parentId": "retrieval-strategies",
      "order": 150,
      "summary": "SQL/指标层/确定性计算与RAG解释分工、数据快照和单位口径。",
      "question": "为什么不能靠检索几段发票文字计算全公司退款总额？",
      "body": "### 需要全量计算时不要用相似片段近似\n\n“上月每个地区退款总额”要求完整数据、明确过滤和可复核聚合。向量检索返回的是若干相关记录，通常不是满足条件的全量集合，因此把检索到的发票交给模型相加，可能漏项、重复或混用币种。RAG可以解释规则，SQL与指标层负责确定性取数和计算。\n\n建议向Agent暴露受控查询或业务指标工具，输入使用明确日期、实体、单位和过滤条件，输出返回结果、数据快照、执行口径和必要明细。PostgreSQL提供关系查询与事务基础；是否与pgvector共库是部署选择，不改变数值必须由完整数据计算的原则。\n\n### 工具应封装业务口径\n\n同一项收入可能包含净额/总额、集团/分部、应计/收付等差异。相比让模型自由拼写任意SQL，稳定的指标API更容易约束口径和权限。确需生成SQL时，应限定可读schema、参数、行数、执行时间和允许操作，不能让自然语言直接获得数据库写权限。\n\n查询结果也要带as-of和来源版本。金融历史分析不能连接今天修订后的表却声称代表过去；教育掌握统计要固定评分器与题目版本；法律事项统计要固定资料覆盖与程序状态。确定性计算只保证按给定输入执行，不保证输入语义正确。\n\n### 验证分成数据与解释两层\n\n准备可人工算出的测试集合，包括空集、重复记录、跨币种、时间边界与权限差异。先核验返回值、分母和过滤，再检查模型是否忠实解释计算结果。模型不得把一个估算字段写成审计确认数字，也不应掩盖缺失数据。\n\n对高代价查询设置预算并缓存合格快照；缓存资格仍受授权与新鲜度限制。若数据不完整，输出覆盖范围与缺项，而不是把没有检索到的记录当作数值为零。最终答案应让读者能复算关键步骤。",
      "blueprint": {
        "inputs": [
          "结构化数据与指标定义",
          "授权、时间、币种及实体条件"
        ],
        "steps": [
          "校验查询范围与只读资格",
          "在完整合格集合上确定性计算",
          "返回快照、口径和明细供解释"
        ],
        "outputs": [
          "可复算的数值结果",
          "有覆盖边界的分析证据"
        ]
      },
      "citations": [
        {
          "url": "https://www.postgresql.org/docs/current/transaction-iso.html",
          "label": "PostgreSQL：事务隔离与一致视图",
          "kind": "official-doc"
        },
        {
          "url": "https://www.sec.gov/search-filings/edgar-application-programming-interfaces",
          "label": "SEC：结构化XBRL资料",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "knowledge-finance-as-of",
          "type": "feeds",
          "reason": "金融聚合必须有时点与单位"
        }
      ]
    },
    {
      "id": "storage-capacity",
      "title": "向量容量与重建空间",
      "aliases": [
        "capacity planning",
        "vector memory",
        "量化"
      ],
      "kind": "concept",
      "parentId": "storage-operations",
      "order": 150,
      "summary": "chunk数量、向量本体、ANN/倒排/文本/WAL/副本/快照、量化和双索引临时空间。",
      "question": "索引除了N乘维度还需要哪些容量？",
      "body": "### 向量本体只是预算的一部分\n\n粗估chunk数量可用N约等于总token数除以切块长度减overlap，结构切块和短段会使实际值偏离。向量本体约为N乘维度d乘每维字节数b：一百万条1536维float32约6.14GB，采用十进制单位，尚未包含索引、文本和任何副本。\n\n整体存储还包括原件、保留版本、解析JSON与图像、倒排和sparse索引、ANN结构、metadata、WAL、replica、snapshot、trace及重建临时空间。Late-interaction多向量表示还需乘每chunk平均子向量数；“文档数相同”并不意味着容量相同。\n\n### 压缩比例不能直接套到总账\n\nfloat16与int8可以减少向量本体，但引擎可能仍保留原向量用于重排或重建。Qdrant量化资料说明压缩向量、原向量与rescore的分工，提示内存节约与磁盘读取延迟是联合取舍。实际索引文件与常驻内存必须测量。\n\n更换embedding或chunking时，新旧generation通常并存；迁移期还要追平增量。若只按常态空间采购，重建或回滚可能恰好在压力最大时失败。备份不应只覆盖向量库，还需原件和权威元数据，否则无法证明恢复出的索引对应哪一版资料。\n\n### 用负载而非数量阈值规划\n\n维度、过滤选择率、候选k、冷热比例、并发与更新频率共同影响所需资源。均值在途请求可用Little定律L约等于到达率乘平均停留时间估算，但不能据此得到p95或故障余量。突发、慢查询和索引构建需要额外容量。\n\n验收分别测热缓存、冷启动、重建期间、更新并发和单节点故障，报告吞吐下p50/p95/p99、实际内存与存储增长。容量公式是预算起点，厂商某项压缩或QPS结果不是本企业工作负载的保证。",
      "blueprint": {
        "inputs": [
          "token、chunk与表示维度",
          "并发、更新、冷热和保留模型"
        ],
        "steps": [
          "估算向量本体与所有附加项",
          "预留副本、迁移和重建空间",
          "用真实负载测量并修正"
        ],
        "outputs": [
          "容量区间和假设",
          "常态及故障余量"
        ]
      },
      "citations": [
        {
          "url": "https://qdrant.tech/documentation/search-tuning/when-your-collection-outgrows-ram/",
          "label": "Qdrant：内存、量化与rescore",
          "kind": "official-doc"
        },
        {
          "url": "https://github.com/pgvector/pgvector",
          "label": "pgvector：表示与索引",
          "kind": "code"
        }
      ],
      "links": [
        {
          "target": "retrieval-embedding-migration",
          "type": "controls",
          "reason": "迁移窗口有双代存储开销"
        },
        {
          "target": "storage-milvus",
          "type": "feeds",
          "reason": "分布式选型来自工作负载"
        }
      ]
    },
    {
      "id": "memory-concurrent-mutation",
      "title": "并发记忆写入与幂等",
      "aliases": [
        "CAS",
        "optimistic concurrency",
        "lost update"
      ],
      "kind": "concept",
      "parentId": "memory-governance",
      "order": 160,
      "summary": "version/CAS/事务、event ID去重、读后重试、细粒度事实项与冲突可见性。",
      "question": "两个Session同时更新同一用户档案，怎样避免互相覆盖？",
      "body": "### 两个正确更新也可能合成错误结果\n\n两个Session同时读取同一profile，一边更新语言偏好，另一边更新项目角色；若都提交整个旧档案，后写者可能覆盖先写者的新值。每个Agent各自推理正确，系统最终状态仍会丢失信息。这是并发写入问题，不能只靠提示词要求“不要覆盖”。\n\nPostgreSQL事务隔离文档解释不同隔离级别及并发行为。实现可选择事务、行锁或乐观版本检查，关键是将读、比较和写组织成明确合同。更强隔离也可能要求应用处理重试，不能将数据库错误隐藏后假装记忆已保存。\n\n### 小粒度与版本检查配合\n\n建议为事实项保留version，提交时声明expected revision；冲突则读取最新值，重新判断是否仍需更新。profile可以使用受校验的patch减少全量改写，但patch也必须对应明确版本，不能按旧字段位置修改已变化的结构。\n\n原始事件使用稳定event ID，记忆整理按事件幂等。任务重试、worker恢复或同一消息重复投递时，不应产生多个相同事实；但两个语义接近、时间不同的真实事件也不能被粗暴去重。\n\n### 冲突保留语义决定\n\n版本检查只发现同时修改，不能自动裁决谁更权威。用户明确纠正、正式资料更新和后台模型推断要按信任与时间处理。特别是旧后台job在用户撤回后完成时，必须拒绝恢复已禁用值，而不是因提交更晚就当成最新事实。\n\n验收用可控并发同时更新不同字段、同一字段、纠正与撤回，检查无丢失更新、无重复事实和可解释冲突。再模拟提交成功但客户端超时，确认重试依赖幂等身份。需要报告真正落库的revision，而不是模型生成的“记住了”回复。",
      "blueprint": {
        "inputs": [
          "事实当前版本与新事件",
          "expected revision和幂等ID"
        ],
        "steps": [
          "事务或CAS检查读写版本",
          "冲突后重新读取与语义裁决",
          "幂等提交并返回实际revision"
        ],
        "outputs": [
          "无丢失更新的事实状态",
          "可审计冲突与重试"
        ]
      },
      "citations": [
        {
          "url": "https://www.postgresql.org/docs/current/transaction-iso.html",
          "label": "PostgreSQL：Transaction isolation",
          "kind": "official-doc"
        },
        {
          "url": "https://help.getzep.com/v4/agent-skills/learning-and-admission",
          "label": "Zep：expected_revision更新示例",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "memory-write-scheduling",
          "type": "feeds",
          "reason": "异步整理与在线更新协调"
        }
      ]
    },
    {
      "id": "retrieval-rag-longcontext-routing",
      "title": "RAG与长上下文分工",
      "aliases": [
        "long context",
        "RAG vs fine-tuning",
        "混合路由"
      ],
      "kind": "concept",
      "parentId": "retrieval-strategies",
      "order": 160,
      "summary": "检索缩小资料域后全文比较、外部事实与稳定行为分工、成本质量路由。",
      "question": "何时检索片段，何时完整读文档，何时才需要微调？",
      "body": "### 按知识更新方式和任务范围选择\n\nRAG适合从大型、持续变化且有权限的数据集中寻找证据；长上下文适合已知范围的完整文档审阅和跨段约束；微调更适合稳定格式、领域表达和工具使用行为。它们不是互斥信仰，也不能因模型窗口变长就停止管理资料资格。\n\n2024年的RAG与Long-Context比较论文研究了混合路由，但当时的模型、价格和任务不能直接外推到当前系统。可借鉴其比较思路：在同一资料、问题和质量标准下测不同路线，再选择满足预算的方案。\n\n### 常见组合是先缩小，再完整阅读\n\n例如比较三份合同的冲突条款，可以先检索确定文档与章节，再让模型读取必要的完整上下文；金融分析可先定位同一时期报告，再读取财务附注。这样保留全文推理能力，又不必每次向模型发送全公司资料。\n\n长上下文增加输入成本、prefill与干扰；RAG则可能漏掉决定性段落。路线选择必须考虑必需证据能否齐全、上下文位置敏感性、授权、新鲜度和任务deadline。仅比较标称窗口容量或单次调用价格不足以判断总体效能。\n\n### 微调不替代事实资格\n\n将频繁变化的制度或法律训练进权重，会增加纠错、删除、引用和权限隔离难度。即使模型学会专业语言，现行事实仍宜通过有来源的工具获取。若问题来自错误工具选择或输出格式，才更可能适合通过示例、prompt或训练改善行为。\n\n验收采用同一holdout比较片段RAG、选定全文和混合路线，记录必要证据覆盖、答案正确性、token、延迟及失败原因。若模型只因读到更多无关内容而更自信，应判定退化，而不是把更长回答当作质量提升。",
      "blueprint": {
        "inputs": [
          "任务范围与资料规模",
          "权限、新鲜度和推理预算"
        ],
        "steps": [
          "判断所需证据粒度",
          "选择片段、全文或混合阅读",
          "用同一holdout比较质量与成本"
        ],
        "outputs": [
          "任务适配的上下文路线",
          "清晰的RAG与训练边界"
        ]
      },
      "citations": [
        {
          "url": "https://arxiv.org/abs/2407.16833",
          "label": "RAG or Long-Context LLMs?",
          "kind": "paper"
        }
      ],
      "links": [
        {
          "target": "retrieval-evidence-assembly",
          "type": "feeds",
          "reason": "路由决定读取片段还是完整资料"
        }
      ]
    },
    {
      "id": "storage-managed-procurement",
      "title": "托管检索与云服务边界",
      "aliases": [
        "managed vector database",
        "cloud RAG",
        "S3 Vectors"
      ],
      "kind": "concept",
      "parentId": "storage-operations",
      "order": 160,
      "summary": "managed Postgres/独立检索/云知识平台三路线、区域/GA/Preview/allowlist、导出恢复、S3 Vectors模式边界。",
      "question": "云优先时哪些能力直接采购，哪些合同仍需自己掌握？",
      "body": "### 云优先把采购与业务合同分开\n\n可以优先采购托管数据库、对象存储、队列与模型推理，把自建投入集中在权限、证据、task/session、评估和能力发布。初期建议同云同地域的精简组合；跨云挑选每项组件可能增加身份、网络、日志、出站费用与尾延迟。\n\n三条路线可对照：托管PostgreSQL加向量扩展；独立托管检索服务；云知识平台。前者减少系统数，中间路线允许独立伸缩，平台路线转移更多接入与检索工作。接口整合越多，越需要验证配置导出、来源可见性和故障定位。\n\n### 新服务也有版本条件\n\n截至2026-10-15，S3 Vectors官方资料说明2026-09-30起新建vector bucket使用ENHANCED索引并支持metadata pre-filter；此前CLASSIC模式可能在匹配资料很少时不足top-k。因此旧测评必须附索引模式，不能仅引用服务名称比较质量。\n\nGoogle当前RAG Engine文档列出区域、GA、Preview及allowlist差别，并单列安全能力支持范围。区域可用、数据驻留承诺、正式可采购与可访问endpoint是不同问题。Azure AI Search的混合接口也不自动替应用完成源ACL治理。\n\n### 用可迁移性约束采购\n\n逐项确认资料是否用于训练、日志与文件保留、删除、地域、固定版本、私网、审计、限流、备份和恢复。承诺可能随endpoint和套餐变化，不能从企业聊天产品推断所有API政策。保存模型无关数据schema与原始证据，避免只留私有response ID。\n\nPoC应使用目标区域的真实连接器、过滤和更新负载，测召回、p95、成本及撤回传播；再试一次导出与恢复。采购成功不是API能调用，而是关键业务合同可证明、数据能带走、故障后能恢复。",
      "blueprint": {
        "inputs": [
          "云环境与资料治理要求",
          "目标负载、预算和采购资格"
        ],
        "steps": [
          "比较精简、独立检索与平台路线",
          "核对区域、版本及endpoint合同",
          "实测检索、撤回、导出与恢复"
        ],
        "outputs": [
          "可采购的托管组合",
          "可迁移和可审计的运行合同"
        ]
      },
      "citations": [
        {
          "url": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors-metadata-filtering.html",
          "label": "S3 Vectors：索引模式与过滤",
          "kind": "official-doc"
        },
        {
          "url": "https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview",
          "label": "Google RAG Engine：区域与支持边界",
          "kind": "official-doc"
        },
        {
          "url": "https://learn.microsoft.com/en-us/azure/search/hybrid-search-overview",
          "label": "Azure AI Search：混合检索",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "storage-postgres-pgvector",
          "type": "complements",
          "reason": "精简托管路线"
        },
        {
          "target": "storage-qdrant",
          "type": "complements",
          "reason": "独立托管向量服务"
        }
      ]
    },
    {
      "id": "memory-recall-policy",
      "title": "记忆召回与上下文投影",
      "aliases": [
        "memory recall",
        "context projection",
        "memory retrieval"
      ],
      "kind": "concept",
      "parentId": "memory-representation",
      "order": 170,
      "summary": "scope/时间/相关性/验证状态/敏感性过滤，事实与episode选择，记忆数据化注入。",
      "question": "当前任务需要哪些旧记忆，哪些应留在库里？",
      "body": "### 从存储集合到当前可用记忆\n\n记忆库可能很大，模型每轮需要的却很少。Recall policy先判断当前用户和任务允许哪些scope、哪个时间点和哪些验证状态，再在其中寻找相关事实或经历。读取策略不是简单取最相似的十段聊天，也不是把所有profile和历史放进prompt。\n\nZep v4将user graph与thread区分，当前文档使用thread.get_context获取相关上下文；这是一个服务接口示例。应用仍需决定哪些资料进入记忆、如何约束搜索范围，以及返回内容以什么通道交给模型。\n\n### 先资格，后相关性\n\n建议依次过滤当前授权、来源有效性、撤回/过期、任务范围与时间，再按问题相关性和用途选择。事实用于约束回答，经历用于参考方法，程序候选只有通过独立发布才可作为合格技能。不能因旧记忆匹配度高就忽略其来源已撤回。\n\n常驻核心块适合小型稳定信息；长事件按需取回；任务摘要链接权威状态。可用混合检索、结构字段和时间条件组合，但要限制重复和token，避免一个高频话题挤掉新纠正。必要时返回原事件供定点核验。\n\n### 记忆是数据，不是权限\n\nZep安全文档明确要求把检索上下文当作非可信数据。它可能包含用户消息、第三方资料或模型生成摘要，不能被插入特权指令通道后当作系统政策。检索到“曾经这样做过”也不构成当前发送、付款或修改配置的授权。\n\n验收比较无记忆与不同召回策略，在相同任务下测成功、token、旧事实使用和跨scope泄漏。单独检查事实是否存在、retriever是否返回、模型是否正确使用，才能知道该改写入、索引还是context组装，而不是反复扩大top-k。",
      "blueprint": {
        "inputs": [
          "当前任务与服务端scope",
          "有时间和验证状态的记忆"
        ],
        "steps": [
          "过滤资格、时间与撤回",
          "选择事实、经历及合格程序",
          "以数据身份注入有限上下文"
        ],
        "outputs": [
          "任务相关记忆包",
          "使用来源与筛选理由"
        ]
      },
      "citations": [
        {
          "url": "https://help.getzep.com/v4/agent-memory-solution",
          "label": "Zep v4：Agent memory",
          "kind": "official-doc"
        },
        {
          "url": "https://help.getzep.com/v4/memory-security",
          "label": "Zep v4：Memory security",
          "kind": "official-doc"
        },
        {
          "url": "https://arxiv.org/abs/2609.22231",
          "label": "EvalMem：写入/检索/生成分层诊断",
          "kind": "paper"
        }
      ],
      "links": [
        {
          "target": "memory-scope-isolation",
          "type": "requires",
          "reason": "授权范围先于相关性"
        },
        {
          "target": "memory-temporal-conflicts",
          "type": "requires",
          "reason": "按as-of选择有效记忆"
        },
        {
          "target": "retrieval-hybrid-fusion",
          "type": "complements",
          "reason": "记忆召回可复用混合搜索"
        },
        {
          "target": "context-assembly",
          "type": "feeds",
          "reason": "记忆是上下文输入而非特权指令"
        },
        {
          "target": "memory-poisoning",
          "type": "controls",
          "reason": "检索不把旧数据升级特权"
        }
      ]
    },
    {
      "id": "retrieval-embedding-migration",
      "title": "Embedding版本与双索引迁移",
      "aliases": [
        "re-embedding",
        "dual index",
        "embedding migration"
      ],
      "kind": "concept",
      "parentId": "retrieval-reliability",
      "order": 170,
      "summary": "模型revision/维度/归一化/截断版本、双索引回填、shadow对照、alias与回滚。",
      "question": "如何升级向量模型而不混合两个不兼容的向量空间？",
      "body": "### 同维度不代表同空间\n\n更换embedding模型、query指令、归一化或截断方式，都可能改变相似性几何结构。即使新旧向量长度相同，也不能把新query直接用于旧文档向量，再认为分数仍可比较。模型ID应与完整表示合同组成独立revision。\n\nQwen3等模型报告给出特定模型和表示方法，pgvector则按维度及距离运算建立索引。两类资料共同说明：生成向量的合同与检索它的合同必须匹配。本文建议双索引迁移，是为控制这层兼容风险，并非某个框架自动保证的能力。\n\n### 新索引先影子运行\n\n保留旧索引服务，后台按相同原件版本构建新generation；记录已回填对象、缺块、失败和最新增量。新query同时走新模型和新索引，旧query仍走旧组合。不能只把旧数据批量迁完，却漏掉迁移期间的新文档和删除事件。\n\n影子查询不影响用户结果，比较各类query的证据召回、过滤表现、rerank和最终答案。原始cosine分数跨模型通常不可直接对比，应使用排名、人工相关性和业务成功等共同指标。改了chunking时再增加一条轴，避免把多个变化的收益混在一起。\n\n### 切换与回滚要成对\n\n达到阈值后原子切换表示revision与索引alias，保留旧版回滚窗口。缓存键要包含revision和index generation；回滚不能恢复已经撤回的权限或已删除资料。容量规划需计入新旧索引并存、构建临时空间和增量追平。\n\n验收覆盖迁移中断、部分回填、模型服务超时、删除和权限变化。发布回执应列出完整性、质量及延迟结果，而非仅报告向量总数相等。模型、维度、距离函数和实际活动索引不匹配时应拒绝查询，避免产生看似正常的错误结果。",
      "blueprint": {
        "inputs": [
          "旧表示合同与索引",
          "新模型revision及同版原件"
        ],
        "steps": [
          "后台双索引回填并追平增量",
          "影子比较召回与端到端结果",
          "成对切换query模型和索引alias"
        ],
        "outputs": [
          "可回滚的新检索generation",
          "完整性与兼容性回执"
        ]
      },
      "citations": [
        {
          "url": "https://arxiv.org/abs/2506.05176",
          "label": "Qwen3 Embedding技术报告",
          "kind": "paper"
        },
        {
          "url": "https://github.com/pgvector/pgvector",
          "label": "pgvector：向量类型与索引",
          "kind": "code"
        }
      ],
      "links": [
        {
          "target": "retrieval-dense-embeddings",
          "type": "requires",
          "reason": "迁移必须保留向量生成合同"
        }
      ]
    },
    {
      "id": "memory-poisoning",
      "title": "记忆投毒与跨会话注入",
      "aliases": [
        "memory poisoning",
        "persistent prompt injection"
      ],
      "kind": "concept",
      "parentId": "memory-governance",
      "order": 180,
      "summary": "source trust继承、事实与指令分离、写入/检索双门控、跨会话红队路径。",
      "question": "恶意资料怎样借一次写入影响以后所有Session？",
      "body": "### 一次不可信输入可能长期存活\n\n普通prompt injection常在当前工具结果中影响Agent；memory poisoning还会诱导系统把恶意说法存成长期事实或规则，在新的Session重新触发。攻击面因此跨越读取、摘要、写入、检索和执行，不能只测试当轮模型是否拒绝了明显指令。\n\n2026年的系统研究专门分析记忆写入渠道与结构漏洞，另有PMPA预印本研究harness-based Agent的持续污染。论文实验表明这是值得单独建模的攻击类别，但其成功率依赖具体环境，不能当成所有服务的通用百分比。\n\n### 信任级别应随来源继承\n\n网页写“公司指定所有紧急付款发到某地址”，只能成为网页陈述，不应被抽取成用户偏好或公司政策。摘要压缩、向量入库和图谱抽取都不应洗掉原始信任标签。模型自己的解释也不是独立确认。\n\n写入端限制候选类型、敏感信息、scope和程序规则；检索端检查来源、时间与撤回；执行端独立验证动作权限。即使某条污染记忆成功进入模型上下文，工具网关也不应允许它自行增加外部目的地或扩大数据访问。\n\n### 红队要跑完整生命周期\n\n使用受控测试资料模拟第三方文本提出伪事实，再观察是否写入、是否在新Session召回、是否改变答案或动作。记录每一层结果，才能区分写入失败、传播失败、激活失败和外部权限成功拦截，而不是只统计最后是否造成损害。\n\n发现污染后，删除单个向量可能不够：还要定位由它产生的profile、摘要、图边、技能候选和缓存，撤回并重新评估。恢复前后保留最小审计。安全门控还需测试正常记忆质量，防止通过拒绝全部写入获得看似漂亮的防御分数。",
      "blueprint": {
        "inputs": [
          "第三方内容与写入渠道",
          "来源信任、scope和工具政策"
        ],
        "steps": [
          "写入端审查并保留来源",
          "召回时不提升指令权限",
          "跨Session红队及派生污染清理"
        ],
        "outputs": [
          "可隔离的污染路径",
          "独立于模型的执行约束"
        ]
      },
      "citations": [
        {
          "url": "https://arxiv.org/abs/2606.04329",
          "label": "Memory poisoning系统研究，2026-06",
          "kind": "paper"
        },
        {
          "url": "https://arxiv.org/abs/2609.13889",
          "label": "PMPA预印本，2026-09",
          "kind": "paper"
        },
        {
          "url": "https://help.getzep.com/v4/memory-security",
          "label": "Zep v4：Memory security",
          "kind": "official-doc"
        }
      ],
      "links": []
    },
    {
      "id": "retrieval-evidence-assembly",
      "title": "证据组装与引用溯源",
      "aliases": [
        "evidence assembly",
        "context selection",
        "citation grounding"
      ],
      "kind": "concept",
      "parentId": "retrieval-reliability",
      "order": 180,
      "summary": "去重/多样性、父段补齐、证据ID、版本与访问复核、token选择、未知与冲突标识。",
      "question": "如何把候选片段变成模型能正确使用的一组证据？",
      "body": "### 检索候选还不是模型上下文\n\n排名靠前的片段可能重复、缺表头、来自旧版本，或者只覆盖问题的一半。证据组装负责把候选变成当前任务可理解、可追溯且预算内的资料集合。它不改写用户目标，也不把检索文本升级为system或developer指令。\n\n建议为每份证据保留稳定ID、源版本、页段、资料类型、有效时间、当前授权状态和内容。对代词或孤立数字补回父段、表头与脚注；对多个问题保留不同证据槽位，避免十个相似段落挤掉唯一的反证或生效日期。\n\n### 预算应分给覆盖而非重复\n\n按真实token计数选择证据，记录每个候选被选或舍弃的原因。长文档不必一律裁成同长度；若问题依赖完整条款，可以读取整个语义单元。必要证据放不下时，可分步读取并保留明确的中间产物，而不是让模型凭摘要补出遗漏事实。\n\nAnthropic的Context engineering讨论按需检索和有限注意预算，Contextual Retrieval则强调片段背景。两者提示组装需要同时考虑局部定位与全局理解，但不意味着把所有历史、记忆和工具输出堆在一起效果更好。\n\n### 引用与事实支持分别检查\n\n最终答案应引用实际被读取的证据版本。引用ID存在、原页可访问、原文支持结论和结论仍适用是不同检查；法律还需法域与效力，金融还需as-of及口径。检索没有发现充分资料时，应保留未知，而非用模型先验填空。\n\n验收检查模型输入里的证据是否覆盖所有必要主张，是否引入越权材料，以及删掉某份证据后相关结论会否降级。将生成错误与组装错误分开归因，才能知道该增加检索、补齐上下文，还是改模型与验证器。",
      "blueprint": {
        "inputs": [
          "重排后的授权候选",
          "问题分解与token预算"
        ],
        "steps": [
          "去重并补齐语义单元",
          "选择互补证据并复核权限版本",
          "以稳定ID交付context builder"
        ],
        "outputs": [
          "可引用的证据包",
          "缺口、冲突和舍弃诊断"
        ]
      },
      "citations": [
        {
          "url": "https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents",
          "label": "Anthropic：Effective context engineering",
          "kind": "official-doc"
        },
        {
          "url": "https://www.anthropic.com/engineering/contextual-retrieval",
          "label": "Anthropic：Contextual Retrieval",
          "kind": "official-doc"
        }
      ],
      "links": [
        {
          "target": "context-assembly",
          "type": "feeds",
          "reason": "向context builder交付数据而非特权指令"
        }
      ]
    },
    {
      "id": "memory-model-migration",
      "title": "记忆策略与模型迁移",
      "aliases": [
        "memory migration",
        "model upgrade",
        "memory policy"
      ],
      "kind": "concept",
      "parentId": "memory-operations",
      "order": 190,
      "summary": "生成/抽取/压缩模型独立版本、保留原事件、重建schema、旧新策略交叉矩阵。",
      "question": "换模型后怎样保留事实又检查记忆使用行为变化？",
      "body": "### 换模型会改变记忆行为\n\n新模型可能更善于抽取，也可能更愿意把推断写成事实；更长上下文也可能增加旧信息干扰。生成模型、记忆抽取器、压缩器和retriever不是同一升级轴。一次全部替换后总分变化，很难知道来自哪一层。\n\n建议为memory policy、schema、抽取prompt、压缩策略、模型snapshot及检索表示分别记录版本。原事件与来源证据仍保留，使新提炼器可以重建或复核，而不是只能接受旧模型留下的一段不可解释摘要。\n\n### 用交叉矩阵定位回归\n\n比较旧模型加旧策略、新模型加旧策略、旧模型加新策略、新模型加新策略。先做协议与schema兼容，再回放真实任务，检查过写、漏写、临时偏好永久化、矛盾裁决、旧事实使用和跨scope访问。Embedding空间迁移另用双索引合同处理。\n\nLongMemEval覆盖时间、更新和拒答等记忆能力；2026年的EvalMem进一步把事实是否写入、是否被检索以及模型能否根据oracle证据作答分开。这类诊断适合判断升级瓶颈，但公开benchmark不能代替企业特有权限与撤回测试。\n\n### 发布配置与运行证据都要记录\n\n离线回放通过后先shadow，再小流量canary。新旧系统可读取相同合格证据，但不要让测试副作用重复执行。保留回滚策略，并确保回滚代码不恢复已经撤回的记忆或权限。供应商不能固定模型snapshot时，应披露复现限制并持续跑sentinel cases。\n\n验收报告应区分存量事实迁移完整性、新事实写入质量、召回质量、最终任务效果及成本。更强模型并不自动使旧记忆正确；只有来源、数据和策略合同可独立检查，长期能力才不会被一次模型更新悄悄改变。",
      "blueprint": {
        "inputs": [
          "旧新模型与memory policy",
          "原事件、schema和领域holdout"
        ],
        "steps": [
          "做交叉版本回放",
          "分层诊断写入、检索与使用",
          "shadow/canary并保留合法回滚"
        ],
        "outputs": [
          "有证据的记忆升级资格",
          "模型无关记忆与回归记录"
        ]
      },
      "citations": [
        {
          "url": "https://arxiv.org/abs/2410.10813",
          "label": "LongMemEval",
          "kind": "paper"
        },
        {
          "url": "https://arxiv.org/abs/2609.22231",
          "label": "EvalMem",
          "kind": "paper"
        }
      ],
      "links": [
        {
          "target": "retrieval-embedding-migration",
          "type": "complements",
          "reason": "向量空间迁移与记忆行为迁移分开"
        },
        {
          "target": "eval-memory-lifecycle",
          "type": "requires",
          "reason": "回放时间/冲突/撤回/跨scope测试"
        },
        {
          "target": "model-upgrade-matrix",
          "type": "complements",
          "reason": "记忆策略与模型输入能力共同测试迁移。"
        },
        {
          "target": "eval-model-migration",
          "type": "requires",
          "reason": "跨模型保留、使用和遗忘需要回归验证。"
        }
      ]
    }
  ]
}