Changelog¶

Unreleased (v0.5-dev)¶

下一发版的累积变更, 完成后 cut.

v0.4.0 (2026-04-26)¶

v0.3.3 后的小步发版, 核心交付 platform 走 Postgres 平台化奠基 — SessionStore 抽接口 + Postgres 后端 + db.Pool 共享 + docker-compose pg service. ADR-0003 立 SessionStore 多副本边界 (三层进程内 pin 物理事实 + sticky routing 必选). v0.4.0 是 v1.0 多副本部署能力的奠基, 但单副本 dev / docker-compose 行为零变化 —— cmd/common 不传 --postgres-dsn 时维持 InMemoryStore 默认, 与 v0.3.3 完全等价.

platform/common 层¶

SessionStore 接口 + InMemoryStore + Postgres + db.Pool (L693) — 4 commit 节奏完整落地, 3-agent review reconcile 后 PM 三轮决策 (Postgres 肯定用 → 整个 platform psql → 拒绝迁移工具+sqlite 走 plain SQL + testcontainers → C3 staging Postgres 跳过待真消费者). 关闭 ADR-0002 § 4 标注的 "in-memory sessions 单实例假设" 限制
platform/common/internal/server/sessionstore/ — SessionStore interface (Create/Get/Delete 三方法, 不要 Touch/List/owner_id 投机表面) + InMemoryStore (sync.RWMutex + map) + PostgresStore (INSERT ON CONFLICT DO NOTHING + RowsAffected==0 单语句原子, 不需显式事务). SessionMetadata 仅 ID + CreatedAt 两字段 (engine.Session pointer 物理只能在 server-local sessionCache, channel/mutex 不可序列化)
platform/common/internal/db/ — 共享 *pgxpool.Pool wrapper + 中央 schema 权威 (platformMigrations append-only CREATE TABLE IF NOT EXISTS list, idempotent Migrate). 当前注册 sessions 表; 后续 staging / verdict-audit 真消费者落地时追加. 不引正式 migration 工具 (1 张表 schema 还在变, plain SQL 自检足够; ≥ 5 张 + 稳定再引)
cmd/common --postgres-dsn flag + db.Pool 顶层 init + Migrate (10s/30s timeout) + defer Close. dsn 空时所有 Postgres 后端子系统回落内存参考实现 (今天 sessionstore.InMemoryStore, 后续 staging 同模式)
server.go 改造: sessions map + mu → sessionStore (持久 metadata, interface 注入) + sessionCache (in-process *engine.Session pointer map, sessionMu RWMutex 独立锁). 4 handler 改造 (handleCreateSession / handleGetSession / handleDeleteSession / handleSendMessage) 用新 store + cache; handlePermissionReply 不动 (走 permCh 不直接 access sessions). TOCTOU race 折叠: RLock-then-Lock 两段 → SessionStore. Create 单语句原子
测试: 13 个 (6 InMemoryStore + 5 testcontainers Postgres 真 pg + 2 db pool), 全模块 -race 全绿. 测试参数化契约 harness 提取留 follow-up (第三后端或 SDK 消费者落地后)
commit 顺序: eec48fe C1 接口 + InMemoryStore drop-in / beaff60 C2 Postgres + db.Pool + docker-compose pg + release.yml POSTGRES_PASSWORD secret / 96e893a C3 ADR-0003 + Caddyfile 注释 / 69500db C4 TODO + CHANGELOG + CLAUDE.md 同步
deploy/docker-compose.yml: 新加 postgres:16-alpine service (健康检查 pg_isready + 持久 volume postgres_data + bridge-internal 不映射 :5432 到 host); common.depends_on.postgres.condition: service_healthy; command 加 --postgres-dsn=postgres://flyto:${POSTGRES_PASSWORD}@postgres: 5432/flyto?sslmode=disable. POSTGRES_PASSWORD 走 .env :?missing fail-loud (跟 ANTHROPIC_API_KEY / FLYTO_PROXY_TOKEN 同模式)
.gitea/workflows/release.yml deploy step 加 export POSTGRES_PASSWORD="${{ secrets.POSTGRES_PASSWORD }}" (跟 ANTHROPIC_API_KEY 同位). PM 已配 Gitea secrets
deploy/Caddyfile /api/v1/* handle 块加单副本 vs 多副本部署区别注释: 多副本必须 lb_policy ip_hash (phase 2 改 header X-Session-ID) 并列所有 replica, 或 k8s Service.sessionAffinity = ClientIP. 当前 reverse_proxy 单 upstream common:8080 不动 (HK-133 phase 1+ 单副本生产, sticky 是 no-op)

关键设计原则¶

三层进程内 pin 物理事实, 平台层只能解一层 (ADR-0003 § 2.4) — server.permCh + Session.pendingPermissions + engine.sessionState .sessions 三层都是进程内 (Go channel + mutex + goroutine 不可序列化). 后两层在 core 引擎层, 平台层即使做完整 SessionStore + PermissionBus pub/sub 也只能解 A 一层. 业界 LangGraph/Vercel/Temporal SessionStore
PermissionBus 双件套需要改 core engine API, 是 RFC 级别留给 v1.0+
多副本必须 LB sticky routing (ADR-0003 § 2.5) — phase 1 ip_hash / k8s ClientIP (NAT 聚集 + 跨设备脱黏可接受); phase 2 触发条件由真投诉驱动, 改 X-Session-ID header lb_policy
接口三方法不要投机表面 — 5 handler 真实操作只有 Create/Get/Delete, Touch/List/owner_id 等会被 dead-field-scanner ratchet 标为死表面. 真消费者出现 (admin UI / 多租户 gating / SLA watchdog) 时方法跟消费者同 commit 落地 (memory feedback_dead_fields_are_implementation_debt)
ephemeral metadata ≠ staging audit (ADR-0003 § 5.5) — staging.Store meta-pattern 复用 (InMemoryStore + SQL-later + tracked-debt), 接口 verbs 不复用 (sessions 是 ephemeral Get/Set/Delete 形态, 不是 staging 7 状态机 + 优化锁)
engine.Session 不动, 借 SnapshotStore — core/pkg/engine/ session_snapshot.go 已有 SnapshotStore 接口 + WithMessages 注入路径, cache miss 自动恢复历史留 follow-up commit, 不在 SessionStore 重新发明序列化 API (channel/mutex/goroutine 不可序列化是物理事实)
plain CREATE IF NOT EXISTS + testcontainers — PM 拍板拒绝过度工程: 不引 migration 工具 (1 张表 schema 还在变, 等 ≥ 5 张稳定再引), 不用 sqlite mock (与 Postgres SQL 方言差别大会掩盖真 bug). 用 testcontainers-go 启真 pg 容器跑测试 (~30s 测试启动 cost 接受)
drop Redis + drop staging Postgres — Redis 元数据 payload 太薄 (id + created_at ~50 字节) 不值, 与 staging / verdict-audit 共享 pg 池更经济; staging Postgres 后端没真消费者 (cmd/common 没装 staging), 跳过等真消费者驱动 (ADR-0003 § 5.5)

已知限制¶

继承 v0.3.0 已知限制 (ML Validator / 熔断器 / cross-transport request-id / SSE 带宽监控 / CAP-4 自动化 / Provider 模型表 / AuditSink / WMS / 场景化教程 / 微信 / .proto 注释), 不重复列出. v0.4.0 新增:

三层进程内 pin 后两层在 core 引擎层 — 真跨副本 live session 失败转移要改 core engine API (engine.Config.PermissionBus + Session. MarshalState/RestoreState), 是 RFC 级别留给 v1.0+ (ADR-0003 § 5.2)
NAT IP 聚集 + 跨设备脱黏 — phase 1 ip_hash / ClientIP 在企业 NAT 后多客户端共享外网 IP 会聚到同副本; 客户端切换网络 IP 会脱黏到另一副本 → 503 (cache miss). phase 2 改 X-Session-ID header 解决, 触发条件由真投诉驱动
Postgres 是新单点 — 池挂 → 所有 SessionStore 操作 503. healthcheck
restart unless-stopped + 持久 volume 是基础保护; HA Postgres (pgpool / patroni / Aurora) 是 v1.0 SLA 课题
engine.SnapshotStore 接线 cache miss 恢复历史 — 留 follow-up commit, 触发条件: 真出现 sticky 失败导致的 503 投诉 (ADR-0003 § 2.6)
staging Postgres 后端待真消费者 — staging 子包当前 cmd/common 没 wire, 行业 platform 也没用. 等 staging 真接入 (验证器 + ML + 审批工作流被 logistics 或其他行业 platform 实际跑) 时同模式追加 (ADR-0003 § 5.5)

发布事实¶

TODO: 52 → 53 done (+1: L693 SessionStore + Postgres 平台化奠基, 4 commit chain eec48fe → beaff60 → 96e893a → 69500db), 13 → 12 open
测试: 13 个 (6 InMemoryStore + 5 testcontainers Postgres + 2 db pool), 全模块 -race 全绿; testcontainers 启 6 个 docker pg 容器实测通过 (~75s 总, docker 不可用 t.Skip 兜底)
依赖: 新增 github.com/jackc/pgx/v5 (runtime, Postgres driver) + github.com/testcontainers/testcontainers-go (test-only) + github.com/testcontainers/testcontainers-go/modules/postgres (test-only). test-only dep 不进 production binary
ADR: ADR-0003 SessionStore 多副本 sticky routing + 三层 pin 物理事实分析 (387 行 8 节体例对齐 ADR-0001/0002)
设计决策工作流: Agent Teams 3 角色并行 review 持续作 default, v0.4 cycle 第 1 次实战 (L693, v0.3 cycle 5 次延续)
CI: release.yml deploy step 加 export POSTGRES_PASSWORD; Gitea secrets 已配
dead-field-scanner baseline: 220 不变 (scanner 只扫 core/, 不扫 platform; 本版改动全在 platform/common)
Tag: v0.4.0 一次性 cut 不走 alpha (与 v0.2.0/v0.3.0 同模式)

文档同步¶

core/docs/adr/0003-session-store-multi-replica-bounds.md 新建 387 行 8 节
deploy/Caddyfile 加 16 行单副本 vs 多副本部署区别注释指向 ADR-0003
core/TODO.md L693 [x] + 4 commit chain + 统计 53/12/65 + 剩 12 项分组
关键观察段加 ADR-0003 + 近期主要动作首条
CLAUDE.md 关键记忆 platform 消费层 9 → 8 项 + 最后变更 L693 段 (v0.3.3 移到上一变更)
CHANGELOG.md v0.4.0 段 (本段) + 起新 Unreleased (v0.5-dev) 空段

v0.3.3 (2026-04-26)¶

L407 follow-up: 内部开发者一站式文档地图 + 双子域文档站 (godoc + docs).

PM 反馈 v0.3.0 cut 的 Swagger UI 只能展示业务 REST API, 不展示 internal Go API + 内部 markdown, 需要"内部开发者方便看文档" 的统一入口. 实现 A + B + C 三件套 (PM 拍板"都要"):

A — README 文档地图 (commit `fea0d27`)¶

升级 root README.md 加 "## 文档地图" section ~70 行
3 个分组: 在线入口 (always-on) / 按目标读者分组 / 5 步入门顺序
7 类读者: Agent / 消费层 / core 贡献者 / Provider / 部署 SRE / TUI / PM
进 Gitea web 看 README 一眼看全 27+ markdown 在哪

B — godoc.flytoex.net 子域 (pkgsite Go API HTML)¶

子域而非 hub.flytoex.net/godoc/* 子路径: pkgsite 内部 href 全是绝对路径 (实测 href="/", href="/git.flytoex.net/yuanwei/flyto-agent"), Caddy strip prefix 后浏览器 link 全断 (跳到 logistics:8080). pkgsite --help 无 --base-path / --mount flag, sub-path 部署不可行
deploy/Dockerfile.godoc 多阶段: golang:1.26-alpine 装 pkgsite + 拷整 monorepo 源 + go mod download all 预解析依赖 → final image 仅含 pkgsite 二进制 + 源 + module cache. ENTRYPOINT pkgsite -http=:8080 -list=false . (首页只列本地 module). cold start ~30-60s (load 472 packages), 后续 in-memory cache
覆盖 core/ 22 子包 + platform/common 所有 exported type, 不鉴权对齐 pkg.go.dev

C — docs.flytoex.net 子域 (mkdocs-material 整合站)¶

deploy/Dockerfile.docs 多阶段: python:3.12-alpine 装 mkdocs-material@9.5.31 (与 staticcheck@v0.7.0 / swag@v1.16.6 / protoc-gen-doc@v1.5.1 同 pin 版模式) + COPY 显式列每个顶层目录 markdown (避免拉 .go/.proto/vendor 让 image 膨胀) → mkdocs build → nginx:alpine serve /usr/share/nginx/html
mkdocs.yml repo 根: docs_dir=/work (绝对路径), config 文件 /config/mkdocs.yml -- mkdocs 不允许 docs_dir = config 父目录, sibling 目录绕开. nav 12 个分组 (入门 / ADR / 核心引擎 / API / Provider / 部署 / TUI / 战略 / 写作规范 / 历史) 串 README + CONSUMERS + CONTRIBUTING + FLYTO
ADR-0001/2 + CHANGELOG + TODO + 7 provider 文档 + architecture + writing-guide
theme material 中文 + indigo + 暗色切换 + tabs/sections/search/code copy

deploy + CI 接线¶

deploy/docker-compose.yml 加 godoc + docs 两 service (compose 内部 expose, Caddy 唯一入口); caddy.depends_on 加 godoc/docs
deploy/Caddyfile 加 godoc.flytoex.net + docs.flytoex.net 两 site block (LE 自动证书 + gzip/zstd, 不鉴权; 跟 hub.flytoex.net 平级三 site block, Caddy SNI 分流)
.gitea/workflows/release.yml build-push job 加 flyto-agent-godoc + flyto-agent-docs 两 build-push step (跟 common + logistics 同 buildx 模式)

DNS (2 条 A 记录, Cloudflare API 加)¶

godoc.flytoex.net → 45.145.229.197 (DNS-only 灰云, 跟 hub 同模式)
docs.flytoex.net → 45.145.229.197 同上

调用 PUT /client/v4/zones/<zoneID>/dns_records 用 PM 给的 API token (Zone:DNS:Edit scope on flytoex.net), 一次 201 Created. 不走 PM web UI.

实测¶

docker build -f deploy/Dockerfile.godoc . → 61.8s 通过, image 跑起来 / 200, /git.flytoex.net/yuanwei/flyto-agent 200
docker build -f deploy/Dockerfile.docs . → 5.83s mkdocs build 通过, nginx serve / 200, <title>Flyto Agent 文档</title> 渲染
mkdocs build INFO 警告 (不阻 build, follow-up 修): docs/evolve-strategy.md 几个章节 anchor link 不存在 (中文 heading anchor 不一致); platform/common/docs/grpc-api.md #google-protobuf-Timestamp anchor 不存在

已知 follow-up¶

pkgsite cold start 30-60s 是首次请求 load 全 module 不是启动. 生产可加 Docker HEALTHCHECK 触发预热, 当前接受首访慢
mkdocs build 几个 anchor warning, 后续清理文档时顺手修
Swagger UI (hub.flytoex.net/swagger/) 与 godoc 现独立 host 不交叉, docs.flytoex.net nav 可加链接到 swagger 入口 (后续)

v0.3.2 (2026-04-26)¶

Hotfix #2, v0.3.1 紧随其后.

v0.3.1 push 后 build-push job 绿 (image 成功 push 到 Gitea registry), 但 deploy job SSH 到 HK-133 跑 docker compose pull 在 parse 阶段 fail: error while interpolating services.common.environment.ANTHROPIC_API_KEY: required variable ANTHROPIC_API_KEY is missing a value

根因: v0.3.0 commit c35e761 给 deploy/docker-compose.yml common.environment 加了 ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:?missing ...} 强制语法, 但 .gitea/workflows/release.yml deploy script 没同步加 export ANTHROPIC_API_KEY=... (跟 FLYTO_PROXY_TOKEN / ADMIN_BASIC_AUTH_* 同模式漏写一行). 服务器仍跑老 image (v0.2.0 时期), /api/v1/* 与 /swagger/* 没生效.

修法两处 (本 hotfix): 1. release.yml deploy script 加 export ANTHROPIC_API_KEY="${{ secrets.ANTHROPIC_API_KEY }}" 2. Gitea repo Settings → Actions → Secrets 配 ANTHROPIC_API_KEY (通过 Gitea API PUT /api/v1/repos/{owner}/{repo}/actions/secrets/{name} 自动化完成, 201 Created)

教训登记 memory (待写): 给 docker-compose 加强制 env 必须同步三处 — compose yaml 自身 / release.yml deploy export / Gitea secret. 漏一处部署链断. feedback_validate_network_path_before_deploy.md v0.3 cycle 内被验证两次 (L407 commit C0 path bug + 本 hotfix env bug).

v0.3.1 (2026-04-26)¶

Hotfix, v0.3.0 紧随其后.

platform/common/go.sum 在 v0.3.0 commit 时少 golang.org/x/net@v0.50.0 的 transitive checksums (net/trace / net/http2 / net/http2/hpack), 平时开发用 GOWORK=on 拉父 workspace 全套 sum 没踩坑, 但 Dockerfile build 走 GOWORK=off, Go 1.26 严格模式直接 missing go.sum entry 拒绝 build. 跑 GOWORK=off go mod tidy 补齐即修复. 触发原因: v0.3.0 cycle go get github.com/swaggo/http-swagger/v2 把 golang.org/x/net v0.49.0 → v0.50.0, 后者新切了 net/trace 等 sub-package, 老 go.sum 不含.

教训登记 memory: workspace 模式下 go get 不会主动跑 go.sum tidy, 升级间接依赖时必须 GOWORK=off go mod tidy 模拟 CI 视角再 verify; release checklist 加 "docker build -f platform/common/Dockerfile ." 实测一次, 不要靠 CI runner 头次发现.

platform/common/go.sum +14 / -4 (golang.org/x/net v0.50.0 transitive hash 补齐); platform/common/go.mod +4 / -2 (indirect dep 重排序)

v0.3.0 (2026-04-26)¶

v0.2.0 之后的三轮发版, 核心交付 platform/common 业务通道激活 + 消费层文档自动化全产物. v0.3 标志 Flyto Agent 从 "core 引擎就绪 + platform 静默" 过渡到 "platform 业务 REST/SSE 通路打通 + Swagger UI / gRPC markdown / CONSUMERS.md 三件套消费层一站式入口". core 引擎层新增 counterfactual + skills/reverse_think + shadowdb 三个子包, 7 provider 全接通 Temperature/TopP sampling 旋钮; ADR-0002 立 "REST 业务 / gRPC 观测" bifurcation, ADR-0001 归档反事实工作流引擎级 enforcement 否决方案.

核心新增 (core 引擎库)¶

counterfactual 子包 + reverse_think Go skill + ReverseThinkingHook reference (L569 缩水) — 反向思维 first-class 数据结构 + Go 化 MiniMax client + platform 层一行启用入口. 6 commit 节奏落地, 原方案 A 完整版 (引擎级 8 模块 1500-2500 行) 经 3-agent review 否决, 走 Option 2-Plus 缩水方案 (4 件套 + ADR-0001 归档否决理由)
core/pkg/counterfactual/ — Deliverable struct 对齐 ~/.claude/skills/reverse-think/SKILL.md JSON schema (hidden_assumptions / failure_scenarios / verdict / verdict_reason 4 核心 + ToolName / Step / DecisionID / OccurredAt 4 元数据). Verdict 常量 (A_holds / B_wins / depends_on_X) 取值开放, Validate 不强制枚举允许 LLM 引入新标签 forward compat. MetadataKey = "flyto.counterfactual.deliverable" 跨包 staging.Record.Metadata 落点常量
core/pkg/skills/reverse_think/ — Client 持 APIKey + Endpoint + Model + MaxTokens (默认 8000 thinking+text 共享池) + HTTPClient + Now 注入. Run(ctx, Prompt, Annotations) (*Deliverable, error) 渲染中文 prompt → POST Anthropic 兼容端点 → unmarshal → stamp metadata → Validate. 不读 MINIMAX_TOKEN_PLAN_KEY env (core 与环境解耦, 调用方注入), 刻意不 strip code-fence 包装 (LLM 遵守度 bug 应暴露非兜底). 4 sentinel error: ErrAPIKeyRequired / ErrEndpointFailed / ErrNoTextContent / ErrParseDeliverable
tools.Metadata.RequiresReverseThinking — 与 RequiresCheckpoint 同源 opt-in flag, 默认 false. 适用非平凡设计空间 (多策略选择 / 失败模式不直观 / schema 漂移), 不适用纯机械 CRUD. 与 RequiresCheckpoint 边界: 后者问 "需要人确认?", 前者问 "agent 应不应该挑战自己的建议?", 两者可叠加 core 不规定顺序由消费 hook 链决定
Deliverable.AsReplayEvent 进化沉淀接线 — counterfactual import evolve 单向, evolve schema-agnostic 不感知 counterfactual. Payload 是 Clone 防 Reflector 摄入时回溯污染 staging.Record. Feedback 返 nil 对齐 evolve.ReplayEvent godoc "决策刚发生 KPI 反馈延迟中". MetaKey 4 常量 (Step/Verdict/Source) 跨包消费方按字面量匹配. 关上 "各行业自写 skill 进化结果停在哪里" 循环: 各行业触发策略可不同, 但 Deliverable schema + AsReplayEvent adapter + evolve.Reflector 学习池在 core 共享统一
platform/common/safetychain/ReverseThinkingHook — Go 行业一行启用入口, 与 Assemble 平行 (Assemble 装 Validator+CircuitBreaker decorator, 本 hook 走 hooks.PreToolUse 不 wrap Tool). Client + Lookup + PromptBuilder + Sink 字段; fail-open advisory (LLM 错不阻断业务, ExitCode=0 + Error 挂供观测层暴露降级状态). DefaultPromptBuilder 仅合格下限, 行业按域覆盖. JSONOutput[counterfactual.MetadataKey] 携带 *Deliverable 让下游 hook / 引擎读不必二次 LLM 调用
业界共识对齐: 调研 agent 拉的 8 框架 (Claude Agent SDK / OpenAI Assistants / Vertex ADK / LangGraph / AutoGen / CrewAI / Semantic Kernel / Cline) 全部走 "engine 提供 hook primitive, 策略由开发者写", 零框架在引擎里 hardcode "决策前必须填五步 deliverable 才能调 tool". 本缩水方案与之同形 (hook 路径 + tool metadata + 开发者自填 PromptBuilder + Sink), 没在 Flyto 引擎核心引入业界都没做的 enforcement primitive
35 测试 -race 全绿: counterfactual 13 + reverse_think 12 + tools 1 新增 + safetychain 9. core + platform/common 双 module build 干净. 4 件套 + reference hook 总量 ~2,131 行 (含双语 godoc + 测试)
3-agent 并行 review (调研业界 8 框架矩阵 + 决策前 gate 形态调查 / 质疑 agent 5 道硬质疑含 tools.Metadata.RequiresCheckpoint 已实装 anchor 修正 / 设计 agent 4 备选 + 边界图 + 拍板假设矩阵). PM 拍板 Option 2-Plus (在原 Option 1 不做 + Option 2 缩水之间加进化沉淀件), core/docs/adr/0001-reverse-thinking-gate.md 归档完整方案对比与否决理由
shadowdb 子包 (L437) — Agent 多轮推理 session 级 shadow 表. 方案 C 列标记隔离 (session_id VARCHAR(64) NOT NULL + filter), 规避 PG TEMP TABLE 在 pooled *sql.DB 下蒸发问题 + driver 分裂. 零 DDL 纯 INSERT/UPDATE/DELETE/SELECT + ?, PG/MySQL/SQLite 通吃
Opener interface + InMemoryOpener 参考实现 (开 / 关 / Reap 孤儿)
Session 结构 + ShadowDB newtype (与 tools/builtin.StagingDB 同族意图标记)
EnforceSessionFilter(sql) 三层防御中层 — quote-aware 剥离字符串/注释后正则校验 session_id=? filter 存在, 不防对抗性 SQL 拼接但捕捉 LLM 随手遗漏
pull-only Reap(ctx, olderThan) — core 不起 goroutine, 平台层从自己的 cron / watchdog 触发
与 staging 边界清晰: staging 决策级 pre-commit (1 decision = 1 Record), shadowdb session 级推理中 scratchpad; 单向 shadow → staging → production, shadow 永不 merge
24 tests 全绿含 -race + 并发 Close/Reap 赛跑测试 (in-memory sqlite SetMaxOpenConns(1) 串行化让测试验证 bookkeeping 竞态不测 driver 内部)
Temperature / TopP cross-provider passthrough (L683) — flyto.Request 加 Temperature *float64 + TopP *float64, 7 provider (anthropic / openai / minimax / gemini / ollama / lmstudio / openrouter) 全部接通 sampling 旋钮. 此前 7 provider 的 Config 与 Stream 一律不传 temperature/top_p, 是 day-1 产品功能缺失而非简单 wire 问题
纯 passthrough + 极小特例: 越界一律不在 flyto 层 clamp, 上游 4xx 自然冒泡为 ErrorEvent (业界共识 — Vercel AI SDK / LangChain / instructor / LlamaIndex 全 passthrough; 仅 litellm 尝试 drop_params 且 bug 频发, issues #8192 / #16090 / #5884)
仅 1 个 wire 时已知冲突预拦: Anthropic + NeedsThinking + Temperature != 1.0 → silent override 1.0 + parameter_overridden WarningEvent; TopP < 0.95 同理 (服务端硬约束 [0.95, 1.0])
不加 OpenAI o-prefix model 检测: server 4xx 已是清晰 ErrorEvent, model-prefix 列表长期维护 burden 不值 (litellm 先例实证)
0 是合法 deterministic 值, *float64 + omitempty 干净分离 nil 与 0 语义; helper flyto.Float(v) 简化指针字段构造
ADR rule of two: 本 commit 是 sampling knob 最小 subset (Temperature + TopP); TopK / Seed / FrequencyPenalty / PresencePenalty 走 follow-up TODO 等真消费者驱动. 业界 Vercel AI SDK / LangChain 同等对待 sampling knobs, cherry-pick 单字段是合理边界
7 provider wire 路径: anthropic 经 internal/transport.MessageRequest + applyThinkingSamplingConstraints helper; openai/ollama/lmstudio/openrouter/minimax(streamOpenAI) 经 internal/wire.StreamRequest + openaiReq json:temperature/top_p top-level; gemini 嵌 generationConfig.temperature/topP; minimax(streamAnthropic) + anthropic 兼容路径同 anthropic
evolve 进化算法层串通: LLMCallOpts.TopP + WithTopP GenOpt + genConfig.TopP + buildMeta 写 meta["top_p"] (ParameterEvolver 与 evaluator 现可追溯候选完整 sampling 配置). FlytoLLMClient adapter 把 LLMCallOpts (float64, zero=未设) 翻译到 flyto.Request (*float64, nil=未设): if v != 0 { req.X = flyto.Float(v) }
23 tests 全绿 (17 wire/provider 层 + 6 evolve 层); baseline 220 → 219 (LLMCallOpts.Temperature 实际 drain — adapter 现在真读 selector)

platform/common 层¶

业务 REST/SSE 通道激活 (L692, ADR-0002) — platform/common/internal/server/server.go 1263 行已写好但未启动的业务 REST/SSE 实现接进 cmd/common, 通过新增 --rest-addr=:8080 启用. 6 commit 节奏完整落地, 3-agent review reconcile + PM 二次拍板. 核心决策: REST/SSE 唯一业务消费通道 + gRPC 仅观测面 (SafetyChain / Health) + 不为 C# 单独加业务 RPC + 不加 grpc-gateway (admin/server.go 已有观测面 REST handler) + Tool 级 SafetyChain 装饰留给行业 platform
server.go 三 API 拆分: buildHandler() http.Handler (mux + middleware chain 抽出) + Serve(ctx, ln) error (主 API, 接收外部 listener + ctx 不接管 signal) + ListenAndServe() (向后兼容 wrapper). 让 cmd/common 用一个 signal handler 统一协调 gRPC + admin HTTP + 业务 REST
OIDC 鉴权统一 (Q2.1 致命修复): 删 Config.BearerToken + authMiddleware raw shared-secret + ConstantTimeCompare 时序防御实现; 加 Config.Verifier *auth.Verifier 走 auth.HTTPMiddleware. dev 模式 (Verifier=nil) 跳过鉴权与 admin/server.go 一致, 让 cmd/common 跨 gRPC + admin HTTP + 业务 REST 共用同一套 OIDC 验签
server 不再内嵌 anthropic provider 写死: Config 删 9 字段 (APIKey / BaseURL / BearerAuth / Model / SystemPrompt / AppendPrompt / Tools / MaxTurns / PermissionMode), 不再读 ANTHROPIC_API_KEY 不再 hard-code "claude-sonnet-4-6". 新增 Attach(eng *engine.Engine) + HandlePermission(ctx, req) 让外部装配 engine 时把 SSE 桥接的 permission.Handler 传给 engine.Config.PermissionHandler 再 Attach
cmd/common/main.go 三 listener wire: 新增 --rest-addr flag (默认空 = 不启动); 启用后装 anthropic provider + engine + s.Attach + net.Listen → s.Serve(restCtx, ln). signal handler 三路协调 SIGINT/SIGTERM 触发 grpcSrv.GracefulStop + httpSrv.Shutdown + restCancel (server.Serve 内部用 10s 上限做 Shutdown). errCh capacity 升 3, wantListeners 按启用 listener 数动态加
Tool 级 SafetyChain 装饰刻意不在 cmd/common 装 — 一刀切 AlwaysApprove + DefaultExtractor 会把所有 Tool 锁同一组合或 fan out 到不匹配 Tool 语义的 wrap. common 保持纯 transport, verdictStore 接线就绪等行业驱动代码 (logistics 等) 在 Tool 注册时装饰并写数据
deploy 配置就绪: deploy/docker-compose.yml common.expose 加 8080 + command 加 --rest-addr=:8080 + environment.ANTHROPIC_API_KEY ${...:?...} 必填; deploy/Caddyfile 加 handle /api/v1/* { reverse_proxy common:8080 { flush_interval -1; transport http { response_header_timeout 0 } } } 让 SSE chunk 透传不被代理缓冲, 模型长思考时不被 idle timeout 切断 (客户端断线检测靠 server.go 15s 心跳); README topology + 业务 REST/SSE curl 例子同步
ADR-0002 立项: core/docs/adr/0002-rest-business-grpc-observation.md 体例对齐 ADR-0001 八节结构 (背景 / 决策 / 评估流程 / 后果 / 替代方案保留 / 触发重评估条件 / 参考 / 修订记录). 核心定性: 与 9 天前 memory feedback_architecture_principle_over_rule_of_two.md 的 "gRPC 优 HTTP / C# 走 gRPC" 是 bifurcation 不是 U-turn (观测仍 gRPC 沿用, 业务用 REST 是补另一面). 调研引用 11 LLM API 矩阵 (Anthropic / OpenAI / Bedrock / Cohere / Mistral / Replicate / Together / Fireworks / Ollama / LM Studio / LangServe) 全 REST/SSE 单通道, Vertex AI 是 gRPC-first 例外但 Google 内部全栈延伸不仿照
测试: server_test.go 既有 546 行用 httptest 直接打 handler 不动; 删 4 raw bearer TestAuth_* (auth.HTTPMiddleware 自身覆盖在 internal/auth 包测试); 新加 TestServer_Serve_RespectsCtx ctx 取消干净返回 + 集成测试 listener bind/shutdown 时序. -race 全绿. cmd/common --help 验证 --rest-addr flag 出现
4 tracked debt 登记: L693 业务 REST 多副本 SessionStore interface (P2, in-memory sessions 单实例假设); L694 gRPC + REST cross-transport request-id / trace 串通 (P3, OpenTelemetry); L695 SSE 1000 单/s 带宽监控 (P3, framing overhead 5-10x); L407 Swagger/OpenAPI (P2, ADR-0002 直接子项)
commit 顺序: 01f08e7 C1 拆 Serve+wrapper / 8189d05 C2 OIDC / 694bd07 C3 Attach + HandlePermission / e1db327 C4 cmd/common --rest-addr / c35e761 C5 deploy / e330774 C6 ADR-0002 + 文档
消费层文档自动化三件套 (L407) — 业务 REST + 观测 gRPC + 顶层 wrapper 一站式入口. ADR-0002 直接子项, 7 commit 节奏 (含 1 path bug 顺手修). queued task 锁定 swag (注解式 OpenAPI 2.0) > huma (code-first 要重写 1263 行 server.go) 路线; SDK 自动生成 (Stainless 模式) 不做 rule of two 等 5+ 语言客户端
platform/common/internal/server/server.go 8 业务 handler (handleHealth/handleAgentRun/handleCreateSession/handleGetSession/handleDeleteSession/handleSendMessage/handlePermissionReply/handleListTools) 加 @Summary @Description @Tags @Accept @Produce @Param @Success @Failure @Router @Security 注解块, 不动业务逻辑. 新增 3 named response type (HealthResponse / StatusResponse / ListToolsResponse) 替代 ad-hoc map[string]any 让 swag schema 准 (handler 仍写 map, JSON 字段名与 struct 一致, 外部契约对齐)
platform/common/internal/server/swag.go seed file 持 service-level @-block (@title Flyto Agent Engine Business REST API / @version v1 / @host hub.flytoex.net / @BasePath /api/v1 / @securityDefinitions.apikey BearerAuth). 放路由旁不放 cmd/common/main.go, single-source-of-truth: 拥有路由的文件也拥有 swagger spec
platform/common/docs/ 4 自动生成产物: swagger.json 22.5K (12 schema, paths) + swagger.yaml 12.3K + docs.go 23.1K (Go embed, side-effect import 让 cmd/common --swagger UI 不读文件系统就嵌入) + grpc-api.md 278 行 (protoc-gen-doc v1.5.1 产, HealthService + SafetyChainService 字段表)
cmd/common --swagger flag opt-in /swagger/* Swagger UI (httpSwagger v2 包内嵌). server.go authMiddleware + rateLimitMiddleware allow-list 加 strings.HasPrefix("/swagger/") 让 UI 在 OIDC 启用时仍可加载, 不烧 rate-limit 预算 (业界共识: Stripe / Anthropic / OpenAI 都公开 OpenAPI spec). 路径在 /api/v1 版本命名空间外, swagger 是 meta artifact 不是版本化业务端点
docs/CONSUMERS.md 顶层 wrapper 133 行: 端口拓扑表 (3 listener × Caddy 路径分流) / 必填环境变量表 / cmd/common 10 flag 表 / OIDC auth 流程图 (含 allow-list 例外 /api/v1/health, OPTIONS, /swagger/*) / 业务 REST 一次性 + 多轮会话 curl 例子 / 观测 gRPC SafetyChain 指引 / 进一步阅读链 (ADR-0002 + deploy/README + TODO + Dockerfile). 链 swagger.json + grpc-api.md 不重复 spec, 只放代码抽不出来的 (流程图 / 端口拓扑 / 跨 service 调用 narrative)
core/Makefile 加 4 个 docs target (docs-swag / docs-grpc / docs-consumers / docs-all) + 升级 docs-install 装 swag@v1.16.6 + protoc-gen-doc@v1.5.1 (与 staticcheck@v0.7.0 同 pin 版模式). 顶部 export PATH := $(shell go env GOPATH)/bin:$(PATH) 让 make 子 shell 找到 install 的二进制; ROOT := git rev-parse --show-toplevel 让 docs-* 从任意 cwd 都能 cd 到 platform/common
.gitea/workflows/release.yml 加 docs drift gate (apt-get protoc + make docs-install + make docs-swag + make docs-grpc + git diff --exit-code 4 产物 swagger.json/yaml/docs.go/grpc-api.md). 与 dead-field-ratchet 平级位于 build-push job 开头. 业界对照: Stripe / Anthropic / OpenAI 都对 OpenAPI spec 跑同等 drift 闸 (PR 必须 commit 生成产物, 否则 CI 红)
deploy/Caddyfile 加 handle /swagger/* { reverse_proxy common:8080 } (无 flush_interval, 静态资源 + JSON 不流式) + deploy/docker-compose.yml common.command 加 --swagger flag (HK-133 lab 默认启用; 生产 deploy 用另份 compose 关闭)
意外+顺手修 (C0 commit 89c38d3): 上一会话 commit 5 (c35e761) Caddyfile handle /api/v1/* 不剥前缀, server.go mux 注册 /v1/* 不匹配, 经 hub.flytoex.net 全 404 (内部直连 localhost:8080/v1/* 才通). L407 之前先打通真实部署链, server.go 8 mux 路由 + server_test.go ~25 处 path + main.go 注释 + ADR-0002 § 2.1 端点形态 + Caddyfile 注释 SSE 例子全部对齐 /api/v1/* 一致 (内外一致, BasePath=/api/v1 干净). 触发 memory feedback_validate_network_path_before_deploy.md 警告再次成立
smoke: ANTHROPIC_API_KEY=fake go run ./cmd/common --rest-addr=:18080 --swagger → /api/v1/health 200 + /swagger/index.html 200 + /swagger/doc.json 200 返回 commit 1 嵌入 spec; caddy:2-alpine validate Caddyfile = "Valid configuration"; docker compose config common.command 4 flag 全到位; build + -race 全绿
commit 顺序: 89c38d3 C0 path bug fix / 26bc732 C1 swag 注解 + spec 首版 / bce7670 C2 --swagger flag + UI / 22b6388 C3 Makefile + CI drift gate + grpc-api.md / a9b04ab C4 CONSUMERS.md / bf5af1d C5 deploy / 本 commit C6 同步

关键设计原则¶

bifurcation, not U-turn (ADR-0002) — 业务 REST / 观测 gRPC 分层. 与 9 天前 memory feedback_architecture_principle_over_rule_of_two.md 的 "gRPC 优 HTTP / C# 走 gRPC" 不冲突: 观测仍 gRPC 沿用, 业务用 REST 是补另一面. 业界对照 11 LLM API (Anthropic / OpenAI / Bedrock / Cohere / Mistral / Replicate / Together / Fireworks / Ollama / LM Studio / LangServe) 全 REST/SSE 单通道, Vertex AI 是 gRPC-first 例外但 Google 内部全栈延伸不仿照
single-source-of-truth (代码即文档) — 业务 REST swag 注解长在 server.go 旁 (拥有路由的文件拥有 swagger spec), 不放 cmd/common/main.go; 观测 gRPC 字段表由 protoc-gen-doc 直读 .proto 注释; CONSUMERS.md 链 auto 产物不重复 spec. CI drift gate 卡 git diff --exit-code 4 产物, 业界对照 Stripe / Anthropic / OpenAI 都对 OpenAPI spec 跑同等闸 (PR 必须 commit 生成产物)
顺手修部署 path bug — L407 commit 0 整体迁移 server.go (8 mux + 6 godoc + 2 middleware allow-list) + Caddyfile (注释举例) + ADR-0002 § 2.1 + main.go (3 处注释) + server_test.go (~25 处) 路径到 /api/v1/* 一致 (上一会话 commit 5 c35e761 Caddyfile handle /api/v1/* 不剥前缀致 server.go 注册 /v1/* 经 hub.flytoex.net 全 404, 没真实经 Caddy 实测). 触发 memory feedback_validate_network_path_before_deploy.md 再次成立
fail-open advisory vs fail-closed gating — ReverseThinkingHook 对 LLM 错不阻断业务 (ExitCode=0 + Error 挂 HookResult.Error 供观测层暴露降级状态), 与 Validator / Staging / CircuitBreaker 的 fail-closed 形成边界互补 (advisory hook vs gating decorator). DefaultPromptBuilder 仅合格下限, 行业按域覆盖
schema-agnostic 旁支 (shadowdb) — session 级 shadow 表用列标记 session_id VARCHAR(64) NOT NULL + filter, PG / MySQL / SQLite 通吃 (规避 PG TEMP TABLE 在 pooled *sql.DB 下蒸发 + driver 分裂). 与 staging 决策级隔离边界清晰: 单向 shadow → staging → production, shadow 永不 merge
sampling knob passthrough — Temperature / TopP 越界一律不在 flyto 层 clamp, 上游 4xx 自然冒泡 (业界共识 — Vercel AI SDK / LangChain / instructor / LlamaIndex 全 passthrough; 仅 litellm 尝试 drop_params 且 bug 频发, issues #8192 / #16090 / #5884). 仅 1 个 in-Request 已知冲突预拦: anthropic + NeedsThinking + Temperature != 1.0 → silent override 1.0 + parameter_overridden WarningEvent
Tool 级安全链装饰是行业 platform 责任 — cmd/common 不调 safetychain.Assemble. 一刀切 AlwaysApprove + DefaultExtractor 会把所有 Tool 锁同一组合或 fan out 到不匹配 Tool 语义的 wrap; common 保持纯 transport, verdictStore 接线就绪等行业驱动代码 (logistics 等) 在 Tool 注册时装饰并写数据 (ADR-0002 § Decision 第 3 条)
swag 注解 > huma code-first — L407 选型: huma (code-first) 要重写 1263 行 server.go, swag (注解式 OpenAPI 2.0) 不动业务逻辑只加注释. SDK 自动生成 (Stainless 模式) 不做 rule of two 等 5+ 语言客户端

已知限制¶

以下功能留待 v0.4+ 完成 (不影响 v0.3 使用):

ML Validator backend 未接入 — core 接口就绪 (validator.Validator + LLMValidator + CompositeValidator + AlwaysApprove + NewValidatedTool nil fail-fast), platform 层接外部 ML HTTP backend 实现 + 装配即启用 (TODO L434, P1)
熔断器未在消费层启用 — core 三态 breaker + VerdictSink 桥接就绪, platform 选作用域 (NoOpScope / DestructiveOnlyScope / PerToolScope) + wire ValidatedTool sink 即启用 (TODO L435, P1)
业务 REST 多副本 SessionStore interface — server.go 当前 process-local in-memory sessions map, k8s 多副本 LB round-robin 立刻挂; v1.0 发版前必做 (TODO L693, P2; ADR-0002 § Consequences 显式标注)
gRPC + REST cross-transport request-id / trace 串通 — 单租户 dogfood 不需要, 上量后 OpenTelemetry 接 Tempo / Jaeger (TODO L694, P3)
SSE 1000 单/s 带宽监控 — prometheus exporter 量化 framing overhead 5-10x, 真到瓶颈再优化 (压缩 / batch / fallback gRPC streaming, v1.0+ 课题; TODO L695, P3)
CAP-4 自动化 × 3 — Flyto CLI 无头自消费 / CI/CD 集成 / WebSearch 前置 (TODO L488-490, P2; 低优工具效率)
Provider 模型表自动更新 — Anthropic / MiniMax / OpenAI / Gemini 新模型上线需手工更 capabilities.json (TODO L454, P2)
AuditSink DB 实现 — 接口就绪, PostgreSQL 写入 + session 查询 + 批量回滚在 platform 层 (TODO L438, P3)
WMS 波次参考实现 — "任务已建待确认" 状态机扩展在 platform 层 (TODO L439, P3)
场景化编排 Go 教程 — examples/orchestration/{ssh_deploy,db_migration,system_config} 三组示例等真消费者驱动 (TODO L408, P3)
微信 ClawBot 接入 — 触发渠道扩展, 当前无业务驱动 (TODO L571, P3)
.proto 字段注释完善 — health.proto 部分字段 description 列空, protoc-gen-doc 自动反映, 后续工作

发布事实¶

TODO: 47 → 52 done (+5: L437 shadowdb / L569 反事实缩水 4 件套 / L683 Temp+TopP / L692 业务 REST 通道 / L407 文档自动化三件套), 14 → 13 open (L693 / L694 / L695 / L407 → 仅 L407 完成出列, L693-695 自 L692 ADR-0002 tracked debt 入列)
测试: counterfactual 13 + reverse_think 12 + tools 1 + safetychain 9 (L569) + shadowdb 24 (L437) + Temp/TopP wire 17 + evolve 6 (L683) + L692 server_test 既有 546 行不动 + 1 ctx 测试 + L407 server smoke (curl 3 个端点) -race 全绿. core + platform/common 双 module build 干净
依赖: 新增 github.com/swaggo/http-swagger/v2 v2.0.2 + github.com/swaggo/files/v2 v2.0.0; 升 github.com/swaggo/swag v1.8.1 → v1.16.6 (CLI 1.16 产 docs.go 用了 LeftDelim/RightDelim 新字段, dep schema 必须对齐)
ADR: ADR-0001 反事实工作流引擎级 enforcement 否决归档 (8 框架业界共识 + 5 套现有 gate 概念重叠 + 范畴错位 + 吞吐数学不成立); ADR-0002 REST 业务 / gRPC 观测 bifurcation 立项 (11 LLM API 矩阵 + grpc-gateway/gRPC-Web 现状 + ConnectRPC 替代). 体例八节结构对齐
设计决策工作流: Agent Teams 3 角色并行 review 持续作 default, v0.3 cycle 实战 5 次 (L437 / L569 / L683 / L692 / L407)
CI: 新增 docs drift gate 与 dead-field-ratchet 平级在 release.yml build-push job 开头 (apt-get protoc + make docs-install + make docs-swag + make docs-grpc + git diff --exit-code 4 产物 swagger.json/yaml/docs.go/grpc-api.md)
Tag: 历史以 v0.1.0-alpha.{1..8} 走 8 次 alpha 后 cut v0.1.0; v0.2.0 一次性 cut 不走 alpha; v0.3.0 同 v0.2.0 一次性 cut

文档同步¶

core/docs/data-safety.md:635 原 CREATE TEMP TABLE shadow_inventory_<sid> 伪 SQL 回销为方案 C 列标记实现, 注明为什么不走 TEMP TABLE 路径
core/TODO.md L437 + L683 + L692 + L407 打勾, 加 L693 / L694 / L695 (P2/P3 tracked debt 自 L692 ADR-0002), v0.3 platform 消费层条目重新计数为 9 (含 L693-695)
core/docs/adr/0002-rest-business-grpc-observation.md 新建, 业务=REST 观测=gRPC bifurcation 决策记录
core/docs/adr/0001-reverse-thinking-gate.md 新建, 反事实工作流引擎级 enforcement 否决归档
docs/CONSUMERS.md 新建顶层 wrapper 133 行, L407 三件套唯一手写部分

v0.2.0 (2026-04-24)¶

v0.1.0 之后的二轮发版, 核心交付 "Agent → staging → Validator → ValidatedTool → CircuitBreaker → WMS API" 完整安全链 core 侧就绪. 引擎层新增 4 个子包 (validator / circuitbreaker / reflector / staging), evolve 9/9 接口矩阵参考实现全部落地, SQL 工具链 3 件套补齐 staging 一跳, platform/common 装配 + 观测 + gRPC 三面暴露就绪供 Go / C# 行业 platform 消费.

核心新增 (core 引擎库)¶

validator 子包 — 可插拔审批契约: RuleValidator (DiffSize / TableWhitelist / Pattern 3 内置规则) / LLMValidator (Flyto provider 桥接) / CompositeValidator (AllMustApprove + Waterfall 2 模式), 显式 AlwaysApprove opt-out, nil fail-fast 构造期 panic
circuitbreaker 子包 — 三态状态机 (Closed / Open / HalfOpen) + Clock DI + VerdictSink 桥接, 订阅 ValidatedTool 的 Verdict 流水自动推进状态
reflector umbrella 包 — 表达 "反射器" 产品抽象, 4 个跨家族 adapter (ValidatorAsEvaluator / EvaluatorAsValidator / ValidatorAsReflector / EvaluatorAsReflector), 不引新顶层接口; 规则 / LLM / ML 后端可互换接入 validator.Validator / evolve.Evaluator / evolve.Reflector 任一同族接口
staging 子包 — 决策包级 staging 表, 7 状态机 (pending_tech → rejected_tech | pending_ml → rejected_ml | approved → executed | failed), 混合控制 Engine (前两段 arc staging 主动调 Validator, 末段 approved → executed/failed 外部推 MarkExecuted/MarkFailed), 可插拔 DependencyGuard + InMemoryStore 参考实现 + 内置 TenantDenyGuard, pull-only query API
evolve v0.2+ 接口矩阵 9/9 参考实现 — Generator / Evaluator / Reflector / ApprovalFunc / ParameterStore / ParameterEvolver / LogReplayer / LogSource / FeedbackChannel / ShadowRunner 全部落地, 闭环 example 单进程跑通 (baseline 1.0 → version 2 的 1.5, divergence 0.1736, shadow delta +0.105)
tools SQL 工具链 3 件套 — 只读校验器 (零 DB 依赖字符串解析) / CAS 乐观锁 (maxRetries=0 fail-fast 默认) / Dry-run 三路 (before + after SELECT + preview_predicate + 100 行 truncate), 支撑 staging 一跳
evolve FlytoLLMClient adapter — flyto.ModelProvider → LLMClient 桥接, LLMGenerator 可驱动任意 provider (anthropic / openai / minimax / gemini / ollama / lmstudio / openrouter); TextEvent 权威 + TextDeltaEvent 兜底避免 anthropic 双倍计数

platform/common 层 (SaaS 基础设施)¶

safetychain 装配包 — 一行 Assemble(inner, v, extractor, scope, sink) tools.Tool 组合 Validator + CircuitBreaker + ValidatedTool decorator, 3 breaker scope 工厂 (NoOpScope / DestructiveOnlyScope / PerToolScope)
admin HTTP 观测端点 — GET /admin/safetychain/verdicts + GET /admin/safetychain/breakers, opt-in 挂载, auth middleware 兜底; VerdictStore 接口 + RingStore bounded 内存实现 O(1) 热路径无分配
gRPC SafetyChainService — 给 C# industry platform 原生通路, 2 RPC (ListVerdicts / ListBreakerStates), bufconn e2e 互操作验证 proto 线格式稳定

关键设计原则¶

fail-closed: Validator 返回 error 视 Block; CompositeValidator Waterfall 任一子 Validator Block 整体 Block; CircuitBreaker Open 直接拒绝调用; nil 依赖构造期 panic 拒启动
schema-agnostic: DiffInput.SourceTool 作分发键, Raw []byte + Metadata map[string]any 携带 opaque 载荷, 引擎层不假设任何行业 schema
显式 opt-out 必须写出来: AlwaysApprove{} / AllowAlwaysGuard{} / NoOpScope() / nil Validator panic — 没有静默默认, industry 刻意关审批必须 code-level 显式动作, 消灭 "以为开了审批实际没开" 的安全假象
产品可替换性: 核心接口 (Validator / Evaluator / Reflector / DependencyGuard / Store / VerdictStore / BreakerScopePolicy) 全部多态可插拔, 规则 / LLM / ML backend 互换接入任一 slot, reflector umbrella + 4 adapter 保证跨家族兼容

已知限制¶

以下功能留待 v0.3+ 完成 (不影响 v0.2 使用):

ML Validator backend 未接入 — core 接口就绪 (validator.Validator + LLMValidator + CompositeValidator + AlwaysApprove + NewValidatedTool nil fail-fast), platform 层接外部 ML HTTP backend 实现 + 装配即启用 (TODO L434)
熔断器未在消费层启用 — core 三态 breaker + VerdictSink 桥接就绪, platform 选作用域 (全熔 / 只熔写 / 每工具一熔) 并 wire ValidatedTool sink 即启用 (TODO L435)
影子表生命周期管理 — Dry-run 工具已做 (模块 23 SQL Dry-run), 多轮推理临时表创建 + 会话结束清理在 platform 层 (TODO L437)
AuditSink DB 实现 — 接口就绪, PostgreSQL 写入 + session 查询 + 批量回滚在 platform 层 (TODO L438)
Temperature cross-provider 契约缺口 — LLMCallOpts.Temperature 被 FlytoLLMClient adapter 刻意忽略 (flyto.Request 最大公约数无 Temperature 字段), 温度控制仍需在 provider 工厂 Config 设置 (TODO L683, P3 设计决策, 侵入式扩 flyto.Request 跨所有 provider)
CAP-4 自动化 × 3 — Flyto CLI 无头自消费 / CI/CD 集成 / WebSearch 前置 (TODO L488-490, P2)
Provider 模型表自动更新 — MiniMax / Gemini 新模型上线需手工更 capabilities.json (TODO L454, P2)
WMS 波次参考实现 — 状态机新增 "任务已建待确认" 在 platform 层 (TODO L439)
反事实工作流引擎级 enforcement — 1500-2500 行改造远期 2026 Q3-Q4 候选 (TODO L569, P3)

发布事实¶

Baseline: 212 → 216 dead fields (+4 合法 tracked debt: Record.TechVerdict / BizVerdict / ExecutionError / ExecutionProof 外部 audit dashboard 消费, core 无内部 reader, 按 feedback_exported_field_delete_needs_review.md)
TODO: 46 → 47 done, 15 → 14 open (L436 staging ✅ check off, 模块 23 SQL × 3 ✅, 安全链 C1-C4 ✅)
测试: staging 47 + reflector 25 + validator / circuitbreaker / safetychain assemble 16 + admin 11 + gRPC server 6 (bufconn e2e) 全绿, race detector 通过
依赖: modernc.org/sqlite test-only dep 落地 (core 第一条非图像处理第三方依赖, SQL CAS 测试用, 生产路径仍仅依赖 database/sql 标准库)
设计决策工作流: Agent Teams 3 角色并行 review 成默认, session 实战 5 次 (SQL CAS / 候选选型 / Validator 接口 / reflector umbrella Option d / staging 5+2 决策)

详细变更¶

以下 sub-sections 保留 session-by-session 技术决策 reasoning 作为 release notes 详录, 供下游 consumer / 技术反思参考.

evolve: v0.2+ 系统级演化接口矩阵 9/9 delivered (2026-04-18)¶

core/pkg/evolve/interfaces.go 定义的 10 个核心接口 (9 interface + 1 func type) 全部落地参考实现, 战略路线见 docs/evolve-strategy.md §7.4.

#	接口	参考实现
1	`Generator`	`generator_llm.go`
2	`Evaluator`	`evaluator_impls.go`
3	`Reflector`	`reflector_impls.go` + `self_reflector.go`
4	`ApprovalFunc`	`evolve.go`
5	`ParameterStore`	`parameter_store_file.go`
6	`ParameterEvolver`	`parameter_evolver_default.go`
7	`LogReplayer`	`default_log_replayer.go`
8	`LogSource`	`log_source_file.go`
9	`FeedbackChannel`	`feedback_channel_file.go`
10	`ShadowRunner`	`shadow_runner_default.go`

闭环 example: core/examples/evolve_closed_loop/main.go -- 9 接口在单进程串联跑通 (baseline 1.0 → version 2 的 1.5, divergence 0.1736, shadow delta +0.105).

领域无关原则¶

所有接口用 any / string / float64 传递业务数据, 不假设任何行业 schema. 具体数据源接入由 consumer 层实现, 引擎只操作抽象接口 (见 memory project_architecture_decisions.md "数据接入边界").

evolve: FlytoLLMClient -- flyto.ModelProvider 桥接 (2026-04-18)¶

core/pkg/evolve/llm_adapter_flyto.go 提供 flyto.ModelProvider -> LLMClient adapter, 让 LLMGenerator 可直接驱动任意 provider (anthropic / openai / minimax / gemini / ollama / lmstudio / openrouter). 事件聚合以 TextEvent 为权威, TextDeltaEvent 作兜底, 避免 anthropic 同时推两者时的双倍计数. ErrorEvent 经 %w ErrLLMFailed 包装, errors.Is(err, ErrLLMFailed) 可用. 非文本事件 (ToolUse / Thinking / Usage / Done / ...) 统一忽略.

限制: flyto.Request 为跨 provider 最大公约数, 不含 Temperature; LLMCallOpts.Temperature 被 adapter 忽略 -- 温度控制仍需在 provider 工厂 Config 设置.

tools: SQL 工具链 3 件套 (2026-04-23)¶

面向 staging / 影子表的三件套, 支撑 AI Agent 写业务 DB 的 staging 一跳 (Agent -> staging -> ML 审批 -> WMS API 写生产). 2026-04-23 commit 981a2ea 分类翻盘, 从原 "消费层不属于引擎层" 挪到引擎层模块 23 -- schema-agnostic / driver-agnostic 通过 StagingDB newtype + *sql.DB DI 由客户端注入 driver, 引擎层仅 database/sql 标准库, 所有客户复用.

组件	位置	commit
SQL 只读校验器	`core/pkg/tools/builtin/sql_validator.go`	`79670c7`
SQL CAS 乐观锁	`core/pkg/tools/builtin/sql_cas.go`	`bf31278`
SQL Dry-run 三路	`core/pkg/tools/builtin/sql_dryrun.go`	`a935604`

要点: CAS maxRetries=0 fail-fast 默认 (Agent 看 version 冲突应重 plan, 非 silent retry), version 非 int 运行时 reject, modernc.org/sqlite test-only dep 落地 (core 第一条非图像处理第三方依赖). Dry-run 方案 E (before + after 都 SELECT) + LLM 传 preview_predicate (工具不 parse SQL) + 100 行 truncate 显式提示. 只读校验器纯字符串 quote-aware 解析零 DB 依赖.

staging: 决策包级 staging 表 + 7 状态机 + 混合控制 Engine (2026-04-24)¶

core/pkg/staging/ 新子包, 管 "Agent 决策 → staging → 审批 → 生产" 链路中 staging 一环. 决策包级 Record (一次 Agent 决策 = 一条 Record, 做法 I 整体打包原子), 7 状态机:

pending_tech -> rejected_tech | pending_ml
pending_ml   -> rejected_ml   | approved
approved     -> executed      | failed

混合控制 (产品决策 Y): Engine 主动调 validator.Validator 推进前两段 arc (ValidateTech / ValidateBiz, fail-closed 语义), 终端 approved → executed/failed 由平台层外部推 (MarkExecuted(id, proof any) / MarkFailed(id, reason)). core 对生产写路径无权限, 无法自驱最后 arc.

接口契约 (产品决策 X): 技术层和业务层两个 slot 都复用 validator.Validator, 不造 TechValidator/BizValidator 新接口. Verdict.Score + Severity 能表达 "SQL 过了但 plan 差" (Warn) 与 "ML 打分 0.3" (Block). 客户用 reflector.EvaluatorAsValidator 把 Evaluator 适配为 Validator 接入任一层.

依赖可插拔 (产品决策 #3): DependencyGuard 接口, nil fail-fast, AllowAlwaysGuard{} 显式 opt-out (对齐 validator.AlwaysApprove 模式); 内置 TenantDenyGuard 示例 (metadata-driven deny-list 典型形态).

客户接入 pull-only (产品决策 #5): Store.List / ListBySession / ListStuck 查询 API, core 不向客户库推送. 客户按需查 (cron / dashboard / 事件 sink 自选).

幂等 + 审计链: MarkExecuted / MarkFailed first-write-wins 保原 proof / reason, 审计不可变性. ListStuck(state, olderThan) 给平台层 watchdog 发现 approved 卡住不推进 (外部 arc 无内置超时, AWS Step Functions task token pattern 借鉴).

文件	内容	行数
`doc.go / state.go / record.go / guard.go`	7 状态 + Record + Query + DependencyGuard + AllowAlwaysGuard + TenantDenyGuard	~350
`store.go / inmemory.go`	Store 接口 9 方法 + InMemoryStore 参考实现	~350
`engine.go`	Engine 混合控制 (NewEngine 4 参 nil fail-fast, 5 方法)	~175
`*_test.go`	47 test 全绿 (race detector 通过)	~700

Baseline 212 → 216 (净 +4 合法 tracked debt: Record.TechVerdict / BizVerdict / ExecutionError / ExecutionProof — 外部 audit dashboard 消费, core 无内部 reader, 按 memory feedback_exported_field_delete_needs_review.md). 设计决策走 Agent Teams 3 角色 review; 产品经理 5 轮产品决策 + 7 条质疑 reconcile (4 硬挡采纳, 2 软挡采纳, 2 保留原决定含前提不成立的). TODO.md L436 check off.

reflector: 产品抽象伞形包 + 4 adapter (2026-04-24)¶

core/pkg/reflector/ 新 umbrella 包, 用于表达 "反射器" 产品抽象 — validator.Validator (sync commit 闸) / evolve.Evaluator (sync 打分) / evolve.Reflector (async 回放) 三个同族接口. 本包不引入新的顶层接口, 只提供跨家族类型安全 adapter, 兑现 "规则 / LLM / ML 后端可互换接入任一同族接口" 的可替换性, 子包代码零改动.

Adapter	作用	关键参数
`ValidatorAsEvaluator`	Validator 包为 Evaluator	`CandidateToDiff` extractor; 可选 `WithRejectFitness` (默认 Approved=false → fitness=0 保守)
`EvaluatorAsValidator`	Evaluator 包为 Validator	`DiffToCandidate` extractor + `threshold` 必传; 可选 `WithName` / `WithBelowThresholdSeverity` / `WithPolicyVersion`
`ValidatorAsReflector`	Validator 包为 Reflector (旁路观察)	`EventToDiff` + `VerdictSink` 必传; OnEvent 永远返回 nil, 错误走 sink
`EvaluatorAsReflector`	Evaluator 包为 Reflector (旁路观察)	`EventToCandidate` + `FitnessSink` 必传

反向 Reflector → Validator/Evaluator 刻意不做 — OnEvent 无返回载荷, 无法反推同步 Verdict 或 fitness. ErrExtractFailed 统一包装 extractor 错误 (errors.Is 可识别). nil src/extract/sink 构造期 panic fail-fast.

设计决策走 Agent Teams 3 角色 review (Option d umbrella 胜出 Option a "真合并三接口") -- 合并超集接口违 Go 惯例 (io.Reader/AWS SDK step/gRPC Unary vs Stream 先例), 且 sync/async 语义不可同一接口承载 (2026-04-23 那次 review 判定的技术事实). umbrella 包以 godoc + 类型安全 adapter 达成 "反射器体系" 产品抽象, 不推翻已 ship 的 validator / evolve 代码.

safety chain: core 层装配就绪 (2026-04-23 / 24)¶

"Agent → staging → Validator → ValidatedTool → CircuitBreaker → WMS API" 安全链 core 侧 7 commit 一次到位, 加上 2026-04-24 的严格化补丁, core 层全部就绪等 platform 装配.

组件	位置	commit
Validator 接口 + DiffInput / Verdict / Severity	`core/pkg/validator/interfaces.go`	`30639fb`
RuleValidator + 3 内置规则 (DiffSize/TableWhitelist/Pattern)	`core/pkg/validator/rule_validator.go`	`e6239c2`
LLMValidator + FlytoLLMClient 桥接 (pkg/flyto 独立副本)	`core/pkg/validator/llm_adapter_flyto.go`	`ca6309e`
CompositeValidator (AllMustApprove / Waterfall 2 模式)	`core/pkg/validator/composite.go`	`8b1d556`
ValidatedTool Decorator + VerdictSink + 3 extractor	`core/pkg/tools/builtin/validated_tool.go`	`6ac07b3`
CircuitBreaker 三态 (Closed/Open/HalfOpen) + Clock DI	`core/pkg/circuitbreaker/breaker.go`	`3342425`
AlwaysApprove 显式 opt-out + NewValidatedTool nil fail-fast	`core/pkg/validator/always_approve.go` + 同上 decorator	`1b0a860`

要点: - schema-agnostic: DiffInput.SourceTool 作分发键, Raw []byte + Metadata map[string]any 携带 opaque 载荷, 引擎不假设任何行业 schema. - fail-closed: Validator 返回 error 视作 Block; CompositeValidator Waterfall 模式任何子 Validator Block 整体 Block. - 熔断桥接: ValidatedTool 每次 Verdict 触发 VerdictSink(toolName, verdict), CircuitBreaker.VerdictSink() helper 订阅即接入 (reject 累积 → Open → Cooldown → HalfOpen 半开试探). - 显式 opt-out 必须写出来: NewValidatedTool(v=nil, ...) 构造期 panic, industry 刻意不要审批必须显式传 validator.AlwaysApprove{}, code review 和审计 dashboard 过滤 ValidatorName="always-approve" 可抓到. 消灭 "以为开了审批实际没开" 的静默安全假象.

消费位点: core 侧全部就绪. 消费层 P1 L434 (ML 验证器) / L435 (熔断器) 等 platform 层装配 — 选 backend (LLM provider / 外部 ML HTTP / 自部署 ML) + 选 breaker 作用域 (全熔 / 只熔写工具 / 每工具一熔) + wire 到 Tool Registry.

safety chain: platform/common 装配层 (2026-04-24, C2)¶

platform/common/safetychain/ 新公共包 (非 internal, Go 行业 platform 可直接 import; C# logistics 走 gRPC, 见 C4). 把 core 的 Validator + CircuitBreaker + ValidatedTool decorator 组合成一行 Assemble() 调用, 产出可注册的 tools.Tool.

组件	形状	作用
`Assemble(inner, v, extractor, scope, sink) tools.Tool`	装配函数	Validator / extractor 为 nil 时由 core 构造期 panic (C1 保证); scope / sink 可 nil
`BreakerScopePolicy`	`func(tools.Tool) *CircuitBreaker`	决定每 Tool 要哪个 breaker; 函数类型非 interface, 行业自定义直接写
`NoOpScope()`	(policy, registry)	不挂 breaker; registry 空
`DestructiveOnlyScope(cfg)`	(policy, registry)	destructive tools 共享 1 breaker, 对齐 "写路径整体保护" 语义
`PerToolScope(cfg)`	(policy, registry)	每 tool 独立 lazy 分配
`BreakerRegistry`	`.Snapshot() map[string]State` + `.Names() []string` sorted	给 C3 admin 端点消费; 每工厂返回句柄

设计决策: - 无默认: industry 不调 Assemble 就没有审批也没有熔断; 没有 safety 是显式 code-level 选择, 不是隐式回退. - 显式 opt-out: Validator 为 nil 由 C1 的 NewValidatedTool panic 守住; industry 刻意 unchecked 必须显式传 validator.AlwaysApprove{}. - 不再抽装配 interface: Assemble 返回的就是 core 的 *builtin.ValidatedTool. 这是接线层不是新契约. Agent Teams 3 角色 review 里"质疑"角色观察"抽 ValidatorAssembler interface 是 YAGNI", 采纳. - fan-out 顺序: industry sink 先 (记录到 observation store 不丢) / breaker sink 后 (推进状态). 供 C3 observation store 消费时保证顺序稳定.

16 test 全绿 (TestAssemble_* × 6 + TestFanOut_AllCombinations + scope 系列 × 9). core baseline 212 不变.

消费位点: 装配层就绪. industry (logistics / erp / crm 等) 选 backend (LLM provider / 外部 ML HTTP) + 选 scope + 调 Assemble 即可启用安全链. C3 加观测端点, C4 加 gRPC 暴露给 C# 消费.

safety chain: admin 观测端点 (2026-04-24, C3)¶

安全链运维可见性: platform/common/safetychain/ 加 VerdictStore 接口 + RingStore bounded 内存实现, 把 Verdict 流水暴露给 admin HTTP 端点让运维和 dashboard 能查实时状态.

组件	形状	说明
`VerdictStore` 接口	`Record(tool, v)` + `Snapshot() []VerdictRecord`	Record 签名对齐 `builtin.VerdictSink`, industry 传 `store.Record` 到 `Assemble` sink 无需 wrapper
`RingStore`	bounded 内存环形, O(1) Record 热路径无分配	容量显式参数, 无默认 (Warn 流量各行业差异大); clock 注入可测, nil 用 wall time
`VerdictRecord`	`{Timestamp, ToolName, Verdict}` 带 json tag	导出结构, 外部观测栈 (日志收集器 / 审计管道) 可直接 decode
`admin.New(..., WithSafetyChain(store, reg))`	variadic option 向后兼容	任一参数 nil 视为不启用 (配对契约); 端点仅 opt-in 时挂载, 默认 404
`GET /admin/safetychain/verdicts`	`[]VerdictRecord` JSON	空 snapshot 返回 `[]` 不是 `null`, 下游无需判 null
`GET /admin/safetychain/breakers`	`[{name, state}]` JSON 按 name 排序	轮询间 JSON diff 稳定

安全考虑: 两端点都走 authed() helper, verifier 非 nil 时套 auth.HTTPMiddleware (和 /admin/tenant 同级). Verdict.Reason 可能携带运营敏感信息 (为什么某 SQL 被 block), 不能未鉴权暴露. /admin/health 仍免鉴权供 Caddy / k8s 探针.

测试: 5 个 RingStore 测试 (cap panic / 未 wrap 顺序 / wrap 后保留最后 N / Snapshot 返回拷贝 / 并发 -race 无 data race / VerdictSink 签名兼容) + 6 个 admin 端点测试 (未 opt-in 返回 404 / partial opt-in 拒绝 / happy path JSON shape / 空 snapshot 返回 [] / breakers 排序 + state 字符串). core baseline 212 不变.

消费位点: core + common 装配 + common 观测都就绪. 只差 C4 gRPC 暴露给 C# logistics. 本 commit 后行业 platform (Go) 的完整消费模式是:

mp := anthropic.NewProvider(...)
v := validator.NewCompositeValidator(...)  // 或 AlwaysApprove{} 显式 opt-out
scope, reg := safetychain.DestructiveOnlyScope(cfg)
store := safetychain.NewRingStore(512, nil)
admin := admin.New("v1", verifier, admin.WithSafetyChain(store, reg))
safe := safetychain.Assemble(innerTool, v, extractor, scope, store.Record)
registry.Register(safe)

safety chain: C# 消费通路 gRPC (2026-04-24, C4)¶

给 platform/industry/logistics/ (C#) 一条原生 gRPC 通路消费安全链状态, 和 C3 的 admin HTTP 形成同源双面暴露. 沿用 HealthService 已经走的 proto + genpb + grpcapi 模式, 不创造新架构.

组件	位置	说明
proto 合约	`platform/common/internal/api/grpc/proto/safetychain.proto`	`flyto.platform.common.safetychain.v1` 命名, csharp_namespace `Flyto.Platform.Common.SafetyChain.V1` 对齐 health
生成代码	`gen/safetychain.pb.go` + `safetychain_grpc.pb.go`	共享 `package genpb`, 和 health 同包
server 实现	`grpcapi.SafetyChainServer{Store, Registry}`	依赖注入, 与 admin.WithSafetyChain 消费同一对 `VerdictStore + BreakerRegistry` (单进程单源)
cmd/common wire	`cmd/common/main.go` 启动默认	构造 `RingStore(1024) + NoOpScope registry`, 同时挂给 admin HTTP 和 gRPC, 默认端到端可访问

2 RPC: - ListVerdicts(ListVerdictsRequest) -> ListVerdictsResponse — 当前 Snapshot 窗口老的在前; 空窗口返空列表不是错 - ListBreakerStates(ListBreakerStatesRequest) -> ListBreakerStatesResponse — 按 Name 排序

设计决策: - proto Verdict 刻意省略 Details 字段 (map[string]any): proto3 无直接等价, 且没有现消费者读 per-rule breakdown. 未来需要时加 repeated DetailEntry { key, json_value }. - Severity / State 用 string 不用 enum: 第三方 Validator / 未来新增 breaker 状态不应强迫 proto schema 升级, 前向兼容优先. - nil Store / Registry 返空列表不报错: 观测端点不能把 "没东西看" 和 "服务挂了" 混淆. cmd/common 已 wire 空 store/registry, 但即使漏 wire 也 graceful degrade. - 默认启用 gRPC safetychain service (和 HealthService 同级别): common 启动即可供 C# stub 对接, 哪怕数据为空. 与 "C3 admin 默认 opt-in 挂" 口径一致: cmd/common 选择了 opt-in.

生成工具链: 需要 protoc-gen-go 和 protoc-gen-go-grpc 插件在 $GOPATH/bin. 本 commit 装了一次:

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

regen 命令 (在 platform/common/internal/api/grpc/proto/ 下跑):

PATH=$GOPATH/bin:$PATH protoc \
  --go_out=../gen --go_opt=paths=source_relative \
  --go-grpc_out=../gen --go-grpc_opt=paths=source_relative \
  safetychain.proto

测试: 6 个 server 测试 (nil-store / nil-registry / 字段 round-trip / 排序 / 空 Snapshot yields empty list / bufconn 端到端 gRPC round-trip). bufconn 测试是 C# stub 互操作的代理证据 — Go client + Go server 经 bufconn 走 proto 序列化往返成功, 说明线格式稳定, C# 用同一 proto 生成 stub 可互操作. core baseline 212 不变.

消费位点: 整条 "Agent → staging → Validator → ValidatedTool → CircuitBreaker → WMS API" 安全链在 core / common 层全部就绪. C# logistics 可用 proto + dotnet add package Grpc.Net.Client 直接消费. 剩的工作落到 industry platform 侧: 选 LLM / ML backend, 装配 Tool 到 engine 消费层, 把真实 Verdict 流水填进 common 的 VerdictStore.

v0.1.0 (2026-04-18)¶

首次公开发布。core/ 引擎库作为独立 Go module 可用。

核心能力¶

引擎运行时 — 多会话管理、子 Agent (fork)、Dream 记忆巩固、Plan 工作流、Token 预算
Provider 层 — Anthropic / Gemini / MiniMax / OpenAI / OpenRouter / Ollama / LM Studio，统一接口
Pricing — 运行时获取模型单价，ModelRegistry 集成，支持多供应商按 token 计费
Hook 系统 — 12 种 HookType，支持 Shell / Callback / Webhook 三种执行后端，session 级隔离
Plugin 系统 — DFS 依赖解析、manifest 验证、能力 probe
Context 压缩 — 三层降级（部分 / 完整 / 反应式），断路器保护
记忆系统 — AI 相关性选择、新鲜度警告、Git/HTTP 团队同步
权限引擎 — 白名单 → 规则 → AI 三层级联，递归 AST 危险命令检测
安全 — 45 条内置 Secret 扫描规则，AuditSink 接口
Agent Teams — Leader/Worker 多 Agent 协调，TaskList 共享任务板
Bridge — SSE / WebSocket 传输，断线重连，串行批量上传
Daemon — 后台守护进程，会话池 + 容量控制，崩溃恢复（指数退避），空闲超时自动关闭
MCP 协议客户端 — JSON-RPC 2.0，多服务器并发管理，stdio / SSE / HTTP 三种传输，Elicitation 支持
自进化（Evolve） — 动态工具构建、Skill 学习、自我反思；接口完备，v1.0 前完善完整能力环路

已知限制¶

以下功能留待 v1.0 前完成（不影响 v0.1 使用）：

AuditSink DB 实现（platform 层）
CAP-4 自动化测试 × 3（core 工具层）
Provider 模型表更新（MiniMax / Gemini）

Changelog¶

Unreleased (v0.5-dev)¶

v0.4.0 (2026-04-26)¶

platform/common 层¶

关键设计原则¶

已知限制¶

发布事实¶

文档同步¶

v0.3.3 (2026-04-26)¶

A — README 文档地图 (commit fea0d27)¶

B — godoc.flytoex.net 子域 (pkgsite Go API HTML)¶

C — docs.flytoex.net 子域 (mkdocs-material 整合站)¶

deploy + CI 接线¶

DNS (2 条 A 记录, Cloudflare API 加)¶

实测¶

已知 follow-up¶

v0.3.2 (2026-04-26)¶

v0.3.1 (2026-04-26)¶

v0.3.0 (2026-04-26)¶

核心新增 (core 引擎库)¶

platform/common 层¶

关键设计原则¶

已知限制¶

发布事实¶

文档同步¶

v0.2.0 (2026-04-24)¶

核心新增 (core 引擎库)¶

platform/common 层 (SaaS 基础设施)¶

关键设计原则¶

已知限制¶

发布事实¶

详细变更¶

evolve: v0.2+ 系统级演化接口矩阵 9/9 delivered (2026-04-18)¶

领域无关原则¶

evolve: FlytoLLMClient -- flyto.ModelProvider 桥接 (2026-04-18)¶

tools: SQL 工具链 3 件套 (2026-04-23)¶

staging: 决策包级 staging 表 + 7 状态机 + 混合控制 Engine (2026-04-24)¶

reflector: 产品抽象伞形包 + 4 adapter (2026-04-24)¶

safety chain: core 层装配就绪 (2026-04-23 / 24)¶

safety chain: platform/common 装配层 (2026-04-24, C2)¶

safety chain: admin 观测端点 (2026-04-24, C3)¶

safety chain: C# 消费通路 gRPC (2026-04-24, C4)¶

v0.1.0 (2026-04-18)¶

核心能力¶

已知限制¶

A — README 文档地图 (commit `fea0d27`)¶