72 lines
11 KiB
Markdown
72 lines
11 KiB
Markdown
# go-sip
|
||
|
||
面向生产的Go SIP调度与执行项目：同一module/二进制通过Cobra提供 `dispatcher`、`agent` 两个业务子命令，分阶段替换Python，保留现有SaaS契约。
|
||
|
||
> **当前状态：已完成本阶段项目内 W01–W14 的单节点/单 Cell/单租户契约、实现与本地/隔离验收；真实 SaaS/MQ、真实供应商/ECS、生产切换及双节点/第二 Cell/双租户延期第二阶段。**
|
||
> 本项目已独立拆仓运营；源码、配置、依赖、迁移、测试、部署和文档均在此目录内维护。远程仓库为 `git.ipao.vip/rogee/go-sip`，本地 Git 默认分支为 `main`；真实外呼仍受逐次授权、capture-first、白名单和时间门禁约束。
|
||
|
||
## 已确认的范围
|
||
|
||
- 使用 **Go 1.27.1**、Cobra单项目双命令和同一发布制品；角色分进程、权限/目录分离。
|
||
- 不接PG：Dispatcher独立SQLite统一任务/配额/outbox；Agent无业务数据库，文本/录音/必要恢复信息落文件。
|
||
- 内部 **Unary gRPC**；Dispatcher配置Agent Endpoint列表，Agent业务启动只需Dispatcher Endpoint，证书/监听/本地资源通过部署提供。
|
||
- 所有Agent共用mTLS证书、Dispatcher身份独立；需Endpoint主动激活/受限节点会话，不能把群组证书当单节点身份。
|
||
- 本次以稳定、快速单节点上线为目标：**1 个 Agent、1 套 Asterisk、1 个单活 Dispatcher、单 Cell、至少 3 家独立 SIP trunk 的契约/协议 fixture、1 个内测商务租户**；双节点、第二 Cell、双租户延期第二阶段。
|
||
- SIP 使用管理平台批准的不可变静态快照；维护窗口发布、排空和实际加载确认保留，在线动态发布/回滚编排暂缓。外呼仅允许 Asia/Shanghai 每日 `09:00`（含）至 `20:00`（不含），窗口外 Dispatcher/Agent fail-closed；按供应商授权登记单 Cell/出口 fixture。
|
||
- 有适用开源库/官方 SDK 时强制复用，不从零手写 SIP/ARI、RTP、MQ、数据库、OSS 或 AI 协议客户端；选库失败先报告阻塞，不静默转自研。
|
||
- 重写完整 Agent：调度控制面、Cell 外呼执行、ARI/RTP/录音、AI 流式适配、Cell 配置接收。
|
||
- 分阶段迁移，最终构建、测试和运行不依赖 Python、父仓库目录或其它业务项目内部代码。
|
||
- Asterisk 继续负责 SIP；独立 SIP 管理平台继续拥有配置管理权，均不纳入重写。
|
||
- SaaS指令/业务结果仍走RabbitMQ；OSS配置源SaaS，Dispatcher统一授权/验证与回传，Agent直传OSS。实时文字事件为 `transcript.updated`，OSS文本用于归档，不能只回文件ID替代文字事件。
|
||
- 本次必须支持 **ASR-only** 与 **ASR + LLM + TTS** 两种模式；本阶段已完成本地/协议隔离双模式验收。百炼/火山ASR、OpenAI兼容LLM、火山TTS的真实供应商能力和生产参数联调仍标第二阶段/未启用，不能将 Mock 写成真实供应商通过；禁止复用旧LLM/TTS。
|
||
- **AI业务配置由Dispatcher按任务agent_version_id调用SaaS已有AI配置GET获取，校验后传给Agent。** 模型、提示词、音色/语速、识别、超时/打断等参数不写死；新版本用于新任务，无需重启，在途通话固定快照。静态SIP发布不代表AI配置静态硬编码。
|
||
- 本轮验收范围收敛为单节点、单 Agent、单 Cell、单租户；保留 tenant_key 原值、独立队列、复合幂等和有界窗口。双节点、第二 Cell、双租户公平/背压/恢复不在本轮开发或验收范围，作为后续阶段。
|
||
- `upload-session/complete/verified`、RabbitMQ ACL/TLS 和 application receipt 本阶段按版本化契约、Schema、fixture 和本地隔离状态机验收；真实 SaaS/MQ 联调延期第二阶段。
|
||
|
||
## 当前本地实现
|
||
|
||
- `contracts/upstream/` 嵌入项目内自包含 W01 基线，记录父源 commit、dirty 继承和 SHA-256；运行时代码读取该包，不读取父目录。
|
||
- `internal/store/` 提供 SQLite inbox、任务、租户/跨 Cell 配额、控制 CAS、replay 和 outbox 事务。
|
||
- `internal/agent/` 只使用文件保存执行状态、transcript、录音/资产和崩溃恢复信息；boot 不释放未知占用；录音通过 Dispatcher 授权的短期 Alibaba OSS presigned PUT 直传，源文件在 verified handoff 前保留。
|
||
- `internal/ai/` 对固定 AI Schema 做不可变快照校验，支持项目内显式 `full_ai`/`asr_only` 分支；`mock_pipeline` 只用于隔离协议/取消/参数测试，不宣称真实供应商已启用。
|
||
- `internal/control/` 提供契约定义的内部查询/控制/replay HTTP 面；外呼命令仍只从 RabbitMQ 进入。
|
||
- `internal/rpc/` 提供 `agent.v1` Unary handlers、mTLS TLS1.3 配置、会话世代/fencing、CAS、permit/fact/upload metadata 边界；Agent CLI 可选启动受证书保护的 gRPC listener，并校验静态 Cell 制品与 AI 授权边界。`internal/calllog/` 提供按手机号 HMAC 关联、掩码和 allow-list JSONL 外呼业务日志，不写原始号码、凭据、音频、转写或 prompt。
|
||
- `internal/health/` 使用 gopsutil 采样主机/进程资源；媒体端口和 AI 配额未接入时明确报告 unknown。`internal/mq/` 默认 bounded prefetch=1、per-tenant DLQ 和 publisher confirm；`make mq-integration-local` 只启动 disposable RabbitMQ。
|
||
- `make acceptance-local` 会校验固定契约、跑 race/vet/build、执行 mock Agent/Dispatcher smoke，并确认 real mode 无凭据时拒绝；Alibaba OSS 实际授权测试由 `AGENT_CALL_OSS_INTEGRATION=1` 门控，使用受控环境变量，不把凭据写入仓库；`make release` 生成带 dirty-source/哈希的 local-development manifest；证据见 [`docs/evidence/20260918-local-development.json`](docs/evidence/20260918-local-development.json)。
|
||
- 直接依赖版本/本地许可证清单见 [`docs/evidence/20260918-dependencies.md`](docs/evidence/20260918-dependencies.md)；门禁结论见 [`docs/evidence/20260918-acceptance-matrix.md`](docs/evidence/20260918-acceptance-matrix.md)；SIP 注册/认证/From/PAI/前缀/选路对比见 [`docs/evidence/20260919-sip-routing-implementation-comparison.md`](docs/evidence/20260919-sip-routing-implementation-comparison.md)，手机号业务日志边界见 [`docs/evidence/20260919-phone-call-business-log.md`](docs/evidence/20260919-phone-call-business-log.md)。
|
||
|
||
这些证据签收本阶段单节点/单 Cell/单租户 P1 适用范围；不等于真实供应商、生产 SaaS/MQ receipt、生产切换或第二阶段拓扑通过。范围和延期项见 [`docs/evidence/20260920-scope-amendment.md`](docs/evidence/20260920-scope-amendment.md)。
|
||
|
||
## 文档
|
||
|
||
后续Agent先读 [项目开发计划与需求阅读索引](docs/plan-0918.md)，按W/子任务确认I/M/G前置并阅读详细设计/权威契约。并行开发按§9登记单写范围、隔离工作区/测试资源和合并回归，由集成负责人统一维护总台账；开发子Agent固定使用 **gpt-5.6-luna＋max＋fast**，不可用时报告阻塞，不静默降级。本轮未启动开发子Agent。
|
||
|
||
| 文档 | 内容 |
|
||
| --- | --- |
|
||
| [plan-0918：开发计划与需求阅读索引](docs/plan-0918.md) | 首读入口：W00–W16及并行子任务、I/M/G关口、R0–R7索引、认领/单写/隔离/合并规则；部署候选前置到W13-a |
|
||
| [Go重写方案 v0.3](docs/Go重写方案_v0.3.md) | 本次单节点/单 Cell/单租户目标、至少3 SIP fixture、双AI模式、P0/P1/第二阶段分期 |
|
||
| [通信与事件数据交互 v0.1](docs/通信与事件数据交互_v0.1.md) | 首发Unary、静态SIP与双模式、§6.1–6.3 SaaS配置来源/参数矩阵/安全边界 |
|
||
| [OpenAPI与MQ字段索引 v0.1](docs/OpenAPI与MQ字段索引_v0.1.md) | 从上游自动提取42个HTTP操作/115个命名组件、Schema与源哈希 |
|
||
| [deploys：物理机 systemd 发布包](deploys/README.md) | 锁定 Debian 13/Go 1.27.1/发布版本，构建并上传不依赖 Docker 的 Agent/Dispatcher 安装包 |
|
||
| [验证与切换验收 v0.3](docs/验证与切换验收_v0.3.md) | 10个首发汇总门禁、88项基线按阶段适用、P2公平性及独立容量验收 |
|
||
| [开源组件选型与复用清单 v0.2](docs/开源组件选型与复用清单_v0.2.md) | §1.3首发基础库/AI SDK选择，§4.3参数能力及锁版/许可/PoC门禁 |
|
||
| [G0开发准备与契约冻结方案 v0.1](docs/G0开发准备与契约冻结提案_v0.1.md) | D01–D10方案已确认；本阶段项目内契约/Proto/PoC按单节点范围签收，真实外部发布和生产联调延期第二阶段 |
|
||
| [AGENTS.md](AGENTS.md) | 本独立子项目的开发与安全约束 |
|
||
|
||
## 独立项目原则
|
||
|
||
- 当前设计文档以本目录 `docs/` 为唯一维护位置，不再向父项目另存一份。
|
||
- 对接协议的现有权威来源仍属于上游；后续在本项目导入带来源、版本和 SHA-256 的不可变契约发布包，不能另写一套同名 Schema。
|
||
- 后续发行包、CI、数据库和运行配置独立。不能靠 `../agent_call`、`../management`、`../sip_mock_server` 或父项目环境文件运行。
|
||
- 业务代码范围仅包括 SIP Agent/Dispatcher 与 Asterisk；RabbitMQ、OSS、AI 供应商及 SaaS API 是 SaaS 提供的基础设施，不在本项目生产包中部署。独立集成测试使用自有隔离数据库、RabbitMQ 和契约 fixture；OSS 数据面使用 Alibaba 官方 Go SDK，Dispatcher 仅签发短期 grant，Agent 直传且不持有 AK/SK；外部 SIP Mock 只能以固定镜像及版本化协议接入，不导入其源码。
|
||
- 真实外呼、云创建、供应商调用和消费授权均是独立门禁，不能由测试成功或本文档自动授权。
|
||
|
||
## 阶段与下一步
|
||
|
||
1. **P0：首发契约与依赖门禁。** 冻结8种事件payload、双AI模式（GAP-08）、SaaS任务AI配置读取/调参（GAP-09）、首发Unary职责、单 Cell 静态快照来源/加载回执、SaaS录音授权和至少3家SIP trunk的配置/协议 fixture。只核验实际采用的SDK；火山TTS参数覆盖、精确版本/许可证未核验前不宣布锁库，不等待未来动态发布/文本OSS归档合同。
|
||
2. **P1：本次单节点内测上线。** 完成单 Cell、单租户、双模式、幂等/控制/配额/恢复/录音安全的本地/隔离闭环；真实 ECS、真实外呼、生产 SaaS/MQ 联调不作为本阶段前置。
|
||
3. **第二阶段：** 真实 SaaS/MQ upload-session/complete/verified、RabbitMQ ACL/TLS/application receipt、真实供应商/ECS 联调，以及双节点、第二 Cell、第二租户公平调度。
|
||
4. **后续另立项：** 在线动态发布、自动跨供应商FALLBACK、多Dispatcher HA/分布式配额、权重借用、文本OSS归档、1000路完整AI/N+1。既有call/command整体补传不是通用回放平台，当前单节点首发仍保留。
|
||
|
||
阶段目标详见主方案§1/§10，首发验收见验收方案§1.1–§1.2；文件名保持不变。本阶段单节点/单 Cell/单租户本地 P1 已签收；真实依赖、供应商、云/拨号、生产 receipt、容量和切换属于第二阶段，证据见 `docs/evidence/20260920-local-p1-acceptance.md`。
|