主题
术语与写作约定
一句话：这一栏的每一篇都按同一套术语、字段名、状态名与证据口径写，读者才能把不同篇里的表拼成一张图，工程同学才能照着字段直接落库。
为什么需要
同一套平台，如果一篇写“等待审批”、另一篇写“阻塞中”、代码里又叫 PENDING_APPROVAL，评审时就要先花半小时对齐词义；如果一篇说“任务完成”，另一篇说“交付成功”，第三篇说“验收通过”，排障时就不知道到底卡在哪一层。
这个专栏已经写到实现级：有表结构、有接口、有状态机、有组件改造清单。越到这个颗粒度，术语不统一带来的不是“读起来别扭”，而是字段对不上、状态迁移对不上、指标对不上。所以需要一份全局约定，管住四件事：
- 同一个概念只用一个词，同一个词只表达一个概念；
- 同一类字段用同一套命名，跨篇可以直接对照；
- 每一篇都按同一套结构写，评审可以逐节检查；
- 发布内容不出现公司名、内部平台名与内部代号，只保留可公开的技术事实。
核心机制
一、文章结构：七段固定，图和表是正文的一部分
每篇按七段写，顺序不变：
| 段落 | 必须回答 | 常见问题 |
|---|---|---|
| 一句话 | 本质、换来了什么、代价是什么 | 写成“XX 是一个优秀的框架” |
| 为什么需要 | 没有它时工程上疼在哪，用具体场景 | 从“随着业务发展”开始 |
| 核心机制 | 从问题推导方案，给字段、状态、失败语义 | 只罗列组件，不讲接缝 |
| 最小上手 | 能复制、能跑通、能验证 | 只给概念，不给步骤 |
| 生产动作 | 参数、监控、排障、灰度、回滚 | 把“注意事项”写成口号 |
| 边界 | 什么场景不该用，代价是什么 | 只讲优点 |
| 讲清楚 | 一段能直接复述的口述版 | 重复目录 |
图和表不是装饰：一张图要能回答“谁连谁、带什么字段、失败怎么办”；一张表要能让读者直接对照实现。没有解释的图、没有验收的表，都算没写完。
二、术语表：一个概念一个词
| 术语 | 定义 | 不要混用 |
|---|---|---|
| 接缝 | 两个组件之间必须约定的边界：字段、权威、失败语义 | 接口、集成点 |
| 权威 | 某个事实最终以谁为准；同一事实只能有一个权威 | 来源、主库 |
| 供给 | 把 Skill、MCP、Agent、Worker 从定义送到运行时的链路 | 发布、部署 |
| 版本 | 不可变的内容标识；运行中的会话绑定创建时的版本 | 发布、标签 |
| 状态 | 任务当前阶段与等待原因的机读记录 | 消息历史、日志 |
| 等待原因 | 任务为什么没有继续执行：审批、输入、工具、外部、排队、限流 | 阻塞、挂起 |
| 预算 | 任务可消耗的资源上限：Token、成本、工具次数、墙钟、步数、重试、沙箱时长、并发 | 账单、配额 |
| 完成证据 | 证明任务结果可接受的记录：产物、测试、引用、审批、回执 | 模型总结、完成语 |
| 证据（Evidence） | 支撑某个评价项的事实材料，分 planned / issued / confirmed 三态；完成证据是它在任务验收上的子集 | 日志、模型总结 |
| 验收 | 业务 owner 对结果的接受决定，独立于操作审批 | 审批、确认 |
| 租约 | 执行者对任务的短期独占权，带 lease_epoch 栅栏 | 锁、会话 |
| 栅栏 | 用递增 epoch 拒绝旧执行者写回的机制 | 版本号、幂等键 |
| 投影 | 从权威状态派生给界面/消息的视图，可重建 | 副本、缓存 |
| 终态 | 不再自动迁移的状态：completed / failed / cancelled / expired | 暂停、等待 |
| 四通信面 | 人机面（AG-UI）/ 能力面（MCP）/ 协作面（A2A）/ 内构面（无标准），按双方身份划分 | 入口、出口、总线 |
| S1–S4 | 请求响应 / 请求域流式 / 任务句柄 / 持久通道；是失效语义分档，不是成熟度 | 同步、异步 |
| 仿真 | 在受控外部世界中运行 SUT，产出可追溯证据，不改变生产事实 | 测试、回放 |
| SUT | 被测 Agent 或其边界内部分；不包含在替身与模拟器中 | 系统、被测对象 |
| 场景（Scenario） | 对一次仿真的目标、参与者、世界事实与验收条件的声明 | 用例、脚本 |
| Manifest | 场景解析后的不可变执行快照，锁定版本、种子与替身 | 配置、参数 |
| Run | 一次 Manifest 的执行；执行、有效性、证据、质量四维状态独立 | 任务、实验 |
| 记录 / 观测 / 证据 | 原始材料 → 事实 → 支撑评价项的材料；三层不可互相替代 | 日志、结论 |
| 轨迹（Trajectory） | 一次 Task Run 的可分析执行记录，含输入、步骤、工具调用与结果 | Trace、Session |
| Pipeline | 把轨迹加工为数据集的版本化处理定义 | 脚本、ETL |
| 黄金数据集 | 题目 + 判据 + 来源的冻结集合，分 tune / validation / holdout | 测试集、样本库 |
| 发布单元（Release） | 模型、Harness、上下文策略、工具、运行时、评测六要素的冻结组合 | 版本、镜像 |
| 预算租约 | 父级授予任务/子任务的额度，可预留、结算、回收、到期 | 配额、限额 |
| 上下文清单 | 一次装配选中的资源、版本、信任层、权限依据与选择原因 | Prompt、上下文 |
| 锁定清单 | 一次 Release/Run 解析后的精确版本与摘要集合 | 依赖清单、锁文件 |
写作时遵守三条：
- 第一次出现一个术语，必须给一句人话解释；后文不要换同义词；
- 组件名用公开名称，能力名用通用词；不把内部代号写进正文；
- 同一个概念在不同篇里出现，字段名与状态名必须一致，不能一篇
tenant、一篇tenant_id混着用。
三、状态、等待与终态：固定枚举
任务阶段固定为：
text
queued | planning | executing | waiting_approval | waiting_input
| waiting_tool | waiting_external | completed | failed | cancelled | expired等待类型固定为：
text
queue | approval | input | tool | external | acceptance | rate_limit | capacity终态固定为：
text
completed | failed | cancelled | expiredaccepted 不是执行阶段，而是 completed 之后的验收结果；delivered 是交付结果，不是任务阶段。三者关系：
如果一篇要新增阶段，先问三个问题：它是否改变资源占用？是否改变谁能推进？是否有独立的超时与恢复动作？三者都不变，就不要加阶段，放到 wait_reason.detail 或 plan 里。
四、对象命名：版本、证据与停止
新增三类对象后，命名要遵守同一套纪律：
| 对象 | 必须带 | 禁止 |
|---|---|---|
发布单元 release_id | 六要素精确版本、manifest_sha256、创建时间 | 用 latest、裸 label、浮动版本作为运行引用 |
仿真 Run run_id | manifest_id、seed、四维状态、trace_id | 用"最近一次"代替具体 Run；把执行状态当质量结论 |
证据 evidence_id | criterion_key、三态（planned / issued / confirmed）、ref + sha256 | 用模型总结、聊天记录、审计日志代替证据 |
预算租约 lease_id | 父级、维度、额度、已用、预留、到期 | 只存"剩余额度"；先调用后补账 |
轨迹 trajectory_id | task_run_id、Release、结果来源、trace_id | 用 session_id 证明"同一任务" |
证据三态的关系是固定的：planned（任务开始时声明需要什么）→ issued（执行者产生并带引用）→ confirmed（验收方确认充分）。任何一段文字只能引用证据 ID，不能把结论写回原始记录。
五、字段与 ID 约定
| 对象 | 命名 | 规则 |
|---|---|---|
| 任务 | task_id | ULID/UUID，全局唯一，不用自增 |
| 会话 | session_id | 由平台生成，不拼用户输入 |
| 租户 | tenant_id | 来自认证结果，不接受客户端自报 |
| 主体 | subject_id | 人、应用、Agent 统一主体 |
| 尝试 | attempt | 从 1 开始，重试加一 |
| 幂等 | idempotency_key | 由调用方提供，作用域 (tenant_id, key) |
| 租约 | lease_owner / lease_epoch | 每次接管 epoch 加一 |
| 版本 | version | 乐观锁，每次状态迁移加一 |
| 追踪 | trace_id / span_id | 遵循 W3C Trace Context |
| 时间 | *_at | UTC、RFC3339，不用本地时间字符串 |
金额与 Token 用十进制定点或整数最小单位，不用浮点；所有“已用/预留/上限”成组出现，不能只存一个“剩余”。
六、表格与图：每张都要能落地
- 对比表至少四列：场景 / 决策点 / 建议默认 / 选错的后果；
- 组件表至少四列：组件 / 职责 / 对外契约 / 不承担什么；
- 状态表至少五列：阶段 / 权威状态 / 等待原因 / 占用资源 / 完成证据；
- 接口表至少五列：方法路径 / 作用 / 请求 / 响应 / 错误；
- 图优先用
flowchart画拓扑、sequenceDiagram画时序、stateDiagram-v2画状态；图后必须有一段解释“这条线为什么这样走”。
数字必须有来源或标注为示例。源码默认值、官方文档、压测结果、经验值要区分开；推测要写“推测”，不要伪装成事实。
七、安全与发布边界
- 不写公司名、内部平台名、内部项目代号、内部产品名；
- 不写真实内网地址、账号、密钥、客户数据；
- 需要举例时用
tenant-a、agent-key、https://gateway.example.com这类占位符； - 引用内部实践时只保留技术结论，去掉组织信息与可识别的业务细节；
- 发布前用脚本检查禁用词与相对链接，检查不通过不发布。
八、评审清单：写完先自己走一遍
| 检查项 | 通过标准 |
|---|---|
| 一句话 | 包含本质、收益、代价，不是功能简介 |
| 为什么需要 | 至少一个具体场景说明“没有它会怎样” |
| 核心机制 | 有字段、状态、失败语义，能推导出设计 |
| 最小上手 | 步骤可执行，有验收判据 |
| 生产动作 | 有参数、监控、灰度、回滚、排障 |
| 边界 | 至少三条“不该用/代价/限制” |
| 讲清楚 | 能口述，不堆术语 |
| 图表 | 每张图有解释，每张表有验收列 |
| 术语 | 与本文约定一致，没有同义词漂移 |
| 安全 | 无公司名、内部名、真实地址与凭据 |
最小上手
新建一篇时，先复制这个骨架，再填内容：
text
# 标题
> 一句话：本质 + 收益 + 代价
## 为什么需要
（一个具体场景 + 三个反例）
## 核心机制
### 一、角色与接缝
### 二、字段与状态
### 三、失败与恢复
（至少一张图 + 两张表）
## 最小上手
（编号步骤 + 验收判据）
## 生产动作
（参数、监控、灰度、回滚、排障）
## 边界
（不该用的场景、代价、限制）
## 讲清楚
（四段口述版）
> 适用：版本/范围 | 初稿 YYYY-MM写完先做三件事：搜索全文的“大概、可能、一般来说”，能换成具体条件的换掉；搜索同义词，统一成一个词；把每个表格的“建议默认”写成可执行的配置或动作。
生产动作
- 术语变更走评审：新增阶段、等待类型、终态，先改本文，再改各篇与代码，禁止各写各的。
- 字段变更走迁移：跨篇引用的字段名变更，要同步更新表结构、接口与指标，不能只改文档。
- 图与代码对齐：架构图按包结构/部署单元画，不凭印象；图里的组件名与代码里的服务名能对上。
- 发布前跑检查：
npm run sync && npm run check && npm run build，修掉链接、篇幅、禁用词与 Mermaid 问题。 - 定期回看：每季度检查一次预览能力、版本号与默认值，过期的结论要标注或删除。
边界
- 约定不是教条：如果某个场景确实需要新状态，先证明它改变资源、推进权或超时语义，再走评审。
- 术语统一不等于文字僵硬：同一概念可以用不同句式解释，但字段名与状态名必须一致。
- 本文不替代各篇：它只定义共同语言，具体机制、参数与取舍仍在各篇展开。
- 安全边界优先于表达：拿不准一个名字是否暴露内部信息时，用通用词，不要赌。
讲清楚
这一栏的共同语言是：接缝、权威、供给、版本、状态、等待原因、预算、完成证据、验收、租约、栅栏、投影、终态。一个概念只用一个词，一个词只表达一个概念。
补上仿真与调优后，还要分清四组对象：场景/Manifest/Run/证据是仿真链，Trace/Session/Trajectory 是观测链，Pipeline/数据集/评估器是数据链，Release/预算租约/上下文清单是治理链。四组各有权威，不能互相代替。
任务阶段、等待类型、终态是固定枚举；要新增，先证明它改变资源占用、推进权或超时语义，否则放到明细里。版本引用必须锁到精确版本与摘要，证据必须区分 planned / issued / confirmed。
每篇按七段写，图和表要能直接对照实现；数字要有来源，推测要标注。
发布内容只保留公开技术事实，不出现公司名、内部平台名、内部代号、真实地址与凭据。
适用：2026 年开源 Agent 平台专栏写作与评审 | 初稿 2026-10