102 lines
7.1 KiB
Markdown
102 lines
7.1 KiB
Markdown
# 共享契约维护
|
||
|
||
## 唯一来源与目录边界
|
||
|
||
最终契约仓库：`git@gitee.com:zzmbac/sip-contracts.git`，分支 `main`。
|
||
SaaS 开发人员与本项目共同维护业务规范、Schema、MQ 拓扑和正常示例。
|
||
本项目的 `contracts/schema` 是 Git submodule，只记录消费的确定提交，不维护另一份本地定义。
|
||
原 `contracts/local` 已移除；`docs/thirds/saas-dispatcher.md` 只提供导航。
|
||
内部 `proto/agent/agent.proto` 仍属于本项目，不移入 SaaS 业务契约。
|
||
|
||
2026-10-10 原 `event_id` 全链路反馈规则已同步至共享提交 `ef3009d`；本项目变更、核验和 SaaS 开发同步说明见 [event_id 生命周期核验](evidence/event-id-lifecycle-20261010.md)。具体消息定义仍只以共享合同为准；此次本地改动未部署，不代表线上反馈已切换。
|
||
任务控制回执及逐字段拒绝反馈规则统一见共享仓库的 `mq-task-control-receipt.schema.json`、`saas-dispatcher.md` 和 `examples/mq-control-{ack,rejected}.json`；SaaS 须同步采用这些入口，不以历史归档提案或旧的仅 status 回执作为现行结构。
|
||
接通时长新增 `answered_at` / `connected_duration_ms`，原 `duration_ms` 不变；共享版本及 SaaS 开发对接说明见 [接通通话时长本地核验](evidence/connected-call-duration-local.md)。本地通过不代表真实呼叫或 SaaS 收讫。
|
||
|
||
| 位置 | 用途 |
|
||
| --- | --- |
|
||
| `contracts/schema/` | 双方对接所需的规范、Schema、拓扑和正常示例；README 分开列出 Schema 和 Examples 用途，业务规范及 MQ 拓扑在正文单独链接说明。 |
|
||
| `contracts/manifest.json` | 本项目记录的冻结历史来源证据；不登记现行合同 hash，不是 SaaS 对接数据。 |
|
||
| `contracts/verify.py`、`contracts/test_verify.py` | 离线检查 Schema 引用、来源和文件完整性，并验证共享目录及 README 的范围。 |
|
||
| `contracts/examples/invalid/` | 本项目拒绝错误消息和配置的测试材料，不作为正常对接示例。 |
|
||
| `contracts/archive/sources/` | 两份历史来源的原字节，只用于验证，不作为当前规范。 |
|
||
| `contracts/AGENTS.md`、`contracts/*_test.go` | 本项目维护规则与契约测试。 |
|
||
|
||
## 获取项目
|
||
|
||
```sh
|
||
git clone --recurse-submodules git@gitee.com:zzmbac/go-sip-agent.git
|
||
# 或在已有项目中获取固定契约版本：
|
||
git submodule update --init --recursive
|
||
```
|
||
|
||
构建仅将固定提交的 Schema、拓扑和正常示例嵌入制品，不包含本项目 manifest、错误示例或历史来源，
|
||
不在运行时读取 Git checkout 或在线加载引用。普通 `make check` 不自动联网追新。
|
||
缺失/未初始化契约、错误来源、未提交修改、指针不一致或未登记的引用均明确失败，没有旧文件兜底。
|
||
发布清单分别记录共享仓库地址、准确提交、拓扑 hash 和本项目验证 manifest 的 hash。
|
||
|
||
## 每次调研或修改契约之前
|
||
|
||
```sh
|
||
# 同步本项目自己的远程分支；失败或分叉时停止，不覆盖现有修改。
|
||
git fetch origin
|
||
# 依据当前分支的上游进行 --ff-only 合并。
|
||
make contracts-update
|
||
```
|
||
|
||
`contracts-update` 获取共享仓库最新 `main` 并只允许快进；更新前验证当前指针、来源及干净状态，
|
||
更新后使用本项目 `contracts/` 中的验证材料检查共享契约。检查通过后仅暂存 `contracts/schema` 新指针。
|
||
现行合同仅以 Git submodule 提交号固定，不再登记逐文件或整包 hash。
|
||
脚本不提交其他文件，不改写历史来源证据，不得回退到旧文件。
|
||
网络错误、分叉或现有契约修改时停止；不自动 stash/reset，不改写已有历史。
|
||
已拉取但尚未暂存的快进允许重新核验；脚本仍拒绝分叉历史、错误来源和子模块内未提交文件，核验成功后才暂存指针。
|
||
|
||
## 修改与同步交付
|
||
|
||
1. 确认已完成上述更新；在共享仓库修改对应 Schema、业务规范、拓扑或正常示例。
|
||
定义只维护一次，聚合入口只引用独立 Schema；README 将 Schema 与 Examples 分表，业务规范和 MQ 拓扑使用独立链接说明。
|
||
2. 在本项目补充错误示例或测试，并核对共享文件变更：
|
||
|
||
```sh
|
||
python3 contracts/verify.py
|
||
python3 -m unittest discover -s contracts -p 'test_*.py' -v
|
||
go test ./contracts
|
||
```
|
||
|
||
验证保留离线 Schema 引用及冻结历史来源检查；现行合同没有需手动刷新的重复 hash。
|
||
3. 提交并推送共享仓库，只选择本次修改的对接文件：
|
||
|
||
```sh
|
||
git -C contracts/schema add <本次契约文件>
|
||
git -C contracts/schema commit -m '<契约变更说明>'
|
||
git -C contracts/schema push origin HEAD:main
|
||
git add contracts/schema
|
||
make contracts-update
|
||
```
|
||
|
||
4. 同步本项目实现、测试和文档；运行 `make contract-check`、`make check`、`make release-check-local`。
|
||
5. 明确暂存本次项目改动及 `contracts/schema` 指针，提交本项目；通知 SaaS 开发人员按同一 commit SHA 同步。
|
||
|
||
**仅推送契约仓库不算完成。所有契约变更必须同步修改本项目；双方评审和联调需记录同一准确提交。**
|
||
已有 P01–P08、A01–A12、K01–K16 项目内证据见 `docs/evidence/saas-dispatcher-p08-acceptance.md`。
|
||
Mock、hash 或离线验证不替代 SaaS、供应商或生产签收。
|
||
|
||
## 2026-10-08 本地适配
|
||
|
||
共享版本 `b502ad2` 的任务线路并发结构已用于配置读取、冻结快照、Dispatcher 选线与原子占用、Agent 入站校验及 SaaS Mock。旧字符串数组直接拒绝；已有占用与未知执行不因配置调整或重启清除。并发从现有 inbox 计算，不新增表或自动改写旧快照。
|
||
|
||
AI 连接的 HTTP 与 WebSocket 地址按调用用途分别使用，缺失时明确拒绝、不互相回退。字段定义仍只在共享仓库维护。
|
||
|
||
本轮本地验证与外部边界见 [`evidence/schema-task-trunk-concurrency-20261008.md`](evidence/schema-task-trunk-concurrency-20261008.md)。没有部署、真实拨号或真实 AI 请求。
|
||
|
||
## ASR 采样率规则与待实现转换
|
||
|
||
共享合同和任务 Schema 已明确：ASR 输入要求不绑定 Agent 内部固定采样率；实际音频与请求声明一致由 Agent 对接边界保证。Schema 不新增采样率必填字段或供应商范围枚举。
|
||
|
||
当前 Agent 尚未实现 ASR 边界转换，仍使用单声道 16 kHz PCM16。转换工作及验收要求见 [`TODO.md`](TODO.md)；新增的 8000/16000 示例与回归测试仅验证配置结构，不证明运行支持或真实供应商兼容。本次不改变运行实现。
|
||
|
||
## 2026-10-09 本地适配
|
||
|
||
共享版本 `adc49ace34a0cdfd21c4de5a20dc6dfc1ab9b9df` 的任务计划可选字段变更已用于本项目合同引用；现有调度行为与新合同一致，无需改写业务逻辑。合同正反例、配置读取、选线边界及省略字段的隔离端到端验证已补齐。
|
||
|
||
本轮差异、验证结果及 A01–A12/K01–K16 对照见 [`evidence/schema-optional-task-schedule-20261009.md`](evidence/schema-optional-task-schedule-20261009.md)。仅暂存了用户明确批准的合同指针，没有提交、推送、部署、真实拨号或真实服务请求。
|