跳转至

项目: Flyto Agent

这是 Flyto Agent Engine 的开发仓库. 我 (Claude Code) 是开发工具, 不是产品本身.

本文是项目宪法, 不是 changelog. 写规则 / 结构 / 关键约束 / 当前状态指针. "做了什么" 全部在 CHANGELOG.md / git log / core/docs/adr/. 流水账累积违反 memory rule feedback_doc_running_journal.md, 已痛戒 (2026-05-03).

强制确认协议 ⛔

最高优先级规则, 违反等于失信.

执行以下操作前, 必须输出确认请求并等待用户回复: - 启动 Agent 子进程 - Write/Edit 任何 .go 文件 - git commit / git push / git tag

确认请求格式: 「⏸️ 等待确认: <要做什么的一句话描述>」

只有收到用户的明确肯定回复后才能执行. - ❌ 不算确认: "讨论吧" / "分析一下" / "看看" / "你觉得呢" - ✅ 算确认: "确认" / "开干" / "可以" / "同意" / "go" / "干吧"

PM 给 batch 授权 (例如 "P0 commit and push") 后, 链路内步骤不再每个⏸️, 但 cut tag / 跨仓 push / 不可逆操作仍单独⏸️.

工作原则

  1. 反向思维: 任何设计决策确认前, 先从反面论证
  2. 升华思维: 不是翻译, 考虑跨行业和未来扩展
  3. 三层防御: 模型交互点必须有指令层 + 参数层 + 兜底层
  4. 精妙/操蛋/升华注释: CLEVER / LEGACY / ELEVATED
  5. 原方案保留: 改动后把原方案作为替代方案写入注释
  6. 零硬编码: 模型 ID 用 ModelRegistry, 路径用配置
  7. 测试即文档: 每个功能有测试
  8. 零外部依赖: 只用 Go 标准库 (core 引擎层)
  9. 跨场景: 引擎核心不假设任何特定场景
  10. 叠加而非替换: 可插拔接口支持多实现共存
  11. 文档同步: 代码改动同步更新受影响文档. 文档过期 = 技术债
  12. Claude 新写注释中英双语: .go 注释 (godoc / 行内 / 块) 含英文 + 中文两段, 先英 后中, 空行分隔 (行内 struct 字段短注释合并: field type // EN. ZH). 中文注释内部标点用半角 ASCII (见 memory feedback_punctuation). 项目术语 / 类型名 / 包名 / FLYTO / ANTHROPIC_API_KEY 保留原文不翻. 存量不回溯, 只做新写部分.

品牌规则

  • 项目名: Flyto Agent, AI 身份: Flyto
  • 代码 / 注释 / 文档中不出现 "Claude Code" 或 "Anthropic"
  • 保留不改的: ANTHROPIC_API_KEY / api.anthropic.com / 模型 ID (claude-sonnet-4-6 等)
  • 配置目录: ~/.flyto/, 指令文件: FLYTO.md
  • 环境变量前缀: FLYTO_*

项目结构

  • core/ — Go 核心引擎库 (原 engine/). 跨场景中性, 不假设任何 vertical. 包含 pkg/engine/ (引擎) + pkg/flyto/ (公共契约) + pkg/tools/ (工具集) + pkg/validator/ + pkg/circuitbreaker/ + pkg/staging/ + pkg/shadowdb/ + pkg/context/ + pkg/reflector/ + pkg/counterfactual/ + 7 provider 子包 (anthropic/openai/minimax/gemini/deepseek/openrouter/ollama+lmstudio) 等. 当前状态详情: core/TODO.md "统计" + CHANGELOG.md 最近 release 段
  • platform/ — SaaS 平台服务, 分两层
  • platform/common/ — 通用 platform (Go, module flyto-platform-common). 飞驼内部共享 SaaS 基础设施: auth (OIDC/JWT) + tenant primitive + gRPC 观测通道 + admin HTTP 观测面 + 业务 REST/SSE (ADR-0002) + sandbox executor + agentprompt (协议字符串) + quotedispatch (main↔sub 转发 loop) + responseguard (JSON verdict 校验). cmd/common 三 listener (:9090 gRPC 观测 / :8081 admin HTTP / :8080 业务 REST/SSE)
  • platform/industry/<vertical>/ — 行业 platforms (C# 为主). 飞驼 C# 团队交付客户的完整 SaaS 产品. 7 vertical 目录已布: logistics (first vertical 验证场景, 报价对账业务) / erp / sales / crm / finance / ads / decision
  • tui/ — 终端 UI (独立 Go module). dogfood CLI + L513 SecretStore 产品端兑现点
  • tools/ — 开发工具 (capability-probe / dead-field-scan 等)
  • deploy/ — Phase 1 部署 (HK-133 lab.flytoex.net, 45.145.229.197). docker-compose 拉 common + logistics + caddy + postgres. Caddyfile 路径分流 (hub.flytoex.net/api/v1/* → common:8080 / /admin/* → common:8081 / 其余 → logistics:8080). LE 证书自动续
  • .gitea/workflows/release.yml — push tag v* 触发, 构建 + push image + SSH HK-133 deploy
  • core/FLYTO.md — 产品宪法 (Flyto Agent 读的, 不是我读的)
  • CLAUDE.md — 本文件 (我读的)

当前状态简述 (会随版本周期更新, 不堆历史)

  • 当前周期: v0.4-dev (v0.3.x 系列已发, v0.3.0 → v0.3.3 见 CHANGELOG)
  • First vertical: 物流报价对账 (yuantong/ytosample.xlsx 系列实证 r 序列, 当前 r31 v7 一轮 4m24s 收敛)
  • 第一消费者: FlySafe (/home/admin/flysafe, USB Work Key 软件), 当前 go.mod replace 直接消费 core/, 计划改为 require stable tag + 中期出 Go SDK 解耦
  • P2 UI 设计阶段启动中: PM 拍板 React + R3F (Three.js + React) + React Flow + framer-motion + shadcn/ui 主框架 + Anthropic Claude Design (4/17 发的 AI 设计师产品 handoff bundle → Claude Code 闭环) 3-7 天入职 + 视觉冲击销售门票 + 业务结果付费理由双线 + "看上去比实际强一档 + 实际同档最优" 产品哲学 (苹果/特斯拉/英伟达模式) + 跨行业不锁物流
  • 关键 ADR (按链接, 不复制内容):
  • core/docs/adr/0001-... 反事实工作流引擎级 enforcement 否决归档
  • core/docs/adr/0002-... REST 业务 / gRPC 观测 bifurcation
  • core/docs/adr/0003-... SessionStore + Postgres 平台化奠基
  • core/docs/adr/0005-... 引擎中性化 13 commit
  • core/docs/adr/0006-... typed ErrorCode + wire→engine fail-loud cause 链
  • core/docs/adr/0007-... Capability tracking 接入纪律
  • core/docs/adr/0008-... Quote-probe 协议层多轮修订 (v1 → v2.2 含 agentprompt 通用包)

最近 commit 看 git log -10 --oneline. 详细变更看 CHANGELOG.md 顶部 Unreleased 段 + 最近发版段.

用户 (PM) 信息 (Claude 协作约束)

  • 产品经理, 非技术背景, 只做产品决策, 技术细节由 Claude 自行决定
  • 刚入职, 公司赛马制, 主管要求保密
  • 偏好: 不堆 list / 业务语言 / 直接说判断不绕 / 反向论证 / 业界对照 / 简短密集 / 不擅自走捷径 / 协议改全消费者一起改 / 范式级修法不打补丁
  • 详细 memory: ~/.claude/projects/-home-admin-ccm/memory/MEMORY.md

索引指针 (不复制内容, 只链)

  • 完整产品 + 工作流 memory: ~/.claude/projects/-home-admin-ccm/memory/MEMORY.md (40+ 条)
  • TODO: core/TODO.md (P0/P1/P2/P3 + 实现债务分档)
  • CHANGELOG: CHANGELOG.md 顶部 Unreleased 段 + 历史 release 段
  • ADR: core/docs/adr/ 目录, 8 节体例对齐
  • CONTRIBUTING: CONTRIBUTING.md 8 条宪法
  • Hard contracts: core/docs/hard-contracts.md 引擎层全部 hard contract 总览 (15 项类型)
  • dev-doc 跨产品文档仓: git.flytoex.net/yuanwei/dev-doc (P2 UI 设计 / FlySafe 协同 / 跨产品研究)

自检清单 (每次代码改动后)

  1. 测试 go test -race -count=1 -timeout 300s 全绿
  2. make -C core docs-swag 重生 swagger (如改了 server REST 注解)
  3. 更新 CHANGELOG.md Unreleased 段
  4. 更新 core/TODO.md 打勾 (如完成已登记项) / 加新 follow-up 项
  5. 关键架构决策走 ADR 8 节体例
  6. 不在 CLAUDE.md prepend 流水账 (本规则 2026-05-03 立)