zhishe-a2a

知设 AI 装修顾问 (zhishe-a2a)

沈阳本地化装修报价 · 自建 Agent 版 通过 Google A2A 0.2.5 协议被千问 APP 调用

当前状态: V1.0 ✅ 跑通端到端 (2026/6/10 验证:28 个测试全绿,真对话调通 DeepSeek)

---

这是什么

一个自建 FastAPI 服务,不是百炼里"创建智能体"。它通过 A2A 0.2.5 协议 暴露给千问 APP,千问发现你的 AgentCard 后主动调你。

千问 APP
   ↓ A2A JSON-RPC
本仓库的 FastAPI 服务(端口 8765)
   ↓ HTTP
DeepSeek(主力 LLM)
   ↓
返回 Agent 回复(末尾固定带"以上内容由 AI 生成,仅供参考")

---

30 秒跑起来

前置

• Python 3.11+ (项目用的是 3.11.9,装在 C:\Users\Administrator\AppData\Local\Programs\Python\Python311)
• DeepSeek API Key (去 https://platform.deepseek.com 申请)

三步启动

# 1. 加 Python 到 PATH(每次新开 shell 都要做)
$env:Path = "C:\Users\Administrator\AppData\Local\Programs\Python\Python311;C:\Users\Administrator\AppData\Local\Programs\Python\Python311\Scripts;" + $env:Path

# 2. 装依赖(首次)
cd "D:\知设Agent生态\千问AI Agent\zhishe-a2a"
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

# 3. 起服务
.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8765

看到 Application startup complete. Uvicorn running on http://127.0.0.1:8765 就 OK。

---

关键端点

---

配置文件 .env

DEEPSEEK_API_KEY=sk-你的key
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat
A2A_SERVER_HOST=0.0.0.0
A2A_SERVER_PORT=8765
LOG_LEVEL=INFO

# 可选:千问调你时的鉴权 key(留空 = 本地联调,不强制鉴权)
A2A_API_KEY=

.env 不要 commit 到 git(已在 .gitignore)。

---

测试

cd "D:\知设Agent生态\千问AI Agent\zhishe-a2a"
.\.venv\Scripts\python.exe -m pytest tests/ -v

当前测试覆盖(28 个):

• test_protocol.py (11个): A2A 协议层 - message/send、错误码、鉴权、LLM mock、JSON-RPC 解析
• test_agents.py (15个): AgentCard 结构、3 个 skill、配置加载、LLM 服务层
• test_smoke.py: Mavis 写权限验证(非 pytest 风格,直接 python tests/test_smoke.py 跑)

跑完预期: 28 passed。

---

调通性验证(2026/6/10 实测)

---

项目结构

zhishe-a2a/
├── app/
│   ├── main.py              # FastAPI 入口,挂 AgentCard + A2A router
│   ├── config.py            # pydantic-settings 读 .env
│   ├── a2a/
│   │   ├── server.py        # A2A 0.2.5 JSON-RPC(message/send)
│   │   └── agent_card.py    # AgentCard 构造(3 skills)
│   ├── api/
│   │   └── health.py        # 健康检查 + LLM 就绪
│   ├── services/
│   │   └── llm.py           # DeepSeek 调用封装 + AI 免责后缀
│   └── prompts/
│       └── xiaozhi.py       # 「小知」system prompt(身份/能力/红线)
├── data/                    # V2.0+ 接入(报价基准/敏感词/系数)
├── tests/
│   ├── test_protocol.py     # 协议层 11 个测试
│   ├── test_agents.py       # AgentCard + 配置 15 个测试
│   └── test_smoke.py        # Mavis 写权限验证
├── examples/
│   ├── client_basic.py      # 同步 A2A 客户端示例
│   └── client_stream.py     # 流式示例(服务端 V1.0 不支持)
├── .env                     # 本地配置(不 commit)
├── .env.example             # 配置模板
├── dev.ps1                  # 一键 PATH + venv 脚本
├── pyproject.toml
├── requirements.txt
├── README.md
└── uvicorn.log / .err       # 运行日志

---

千问管控台接入流程

1. 阿里云百炼管控台 → 「三方 Agent」管理
2. 点"接入三方 Agent"
3. 填 https://你的域名/.well-known/agent.json
4. 配 AgentCard 详情(自动发现)
5. 千问按 A2A 协议调你

公网部署:参考下面"部署"小节。

---

部署

联调(5 分钟):ngrok

ngrok http 8765
# 拿到 https://xxxx.ngrok-free.app
# 写到 .env:PUBLIC_BASE_URL=https://xxxx.ngrok-free.app
# 重启服务

正式:阿里云轻量 99 元/年 + 备案域名 + HTTPS

详见 deploy/README.md(待补)。

---

合规要点(已固化在 prompt)

• ✅ 不持有具体价格数据
• ✅ 不主动提任何外部联系方式(微信/二维码/电话)
• ✅ 不推荐具体装修公司
• ✅ 所有"线下服务"引导用户在千问 APP 内继续对话
• ✅ 末尾固定加"以上内容由 AI 生成,仅供参考"
• ✅ 不用绝对化用语(违反广告法)

---

战略定位(从 V1.0 计划书继承)

• 第一性原理:数字智能进化效率 > 生物智能
• 1 人 + AI 顶 10 人团队
• 沈阳本地化数据护城河
• 三层枷锁:身份 / 工具 / 利益
• 三阶段架构:单体(V1.0 当前) → 主从 → 市场机制

---

V1.0 验收(2026/6/10 更新)

---

内容安全与三层存储策略

核心原则:Gotchas 知识库是知设的核心资产,必须与外部平台隔离。语雀/公众号只做脱敏科普引流,不存核心内容。

三层存储架构

脱敏规则

• 可以公开: 国家标准条文(GB规范)、通用施工工艺流程、业主常见问题FAQ
• 脱敏后公开: 特定城市行情数据(去掉城市名和具体价格,保留趋势判断)
• 绝不公开: 具体金额案例(如"签8000实收18000")、Gotchas库独家分析框架、用户真实案例和反馈

平台安全对比

阿里生态平台关系

第一层 · 模型研发层(底层能力,不直接面向你)
  通义千问团队(Qwen系列) | 百灵团队(Ling系列) | DeepSeek合作(第三方)
     ↓ 提供模型能力
第二层 · 模型服务层 ✅已进驻
  百炼平台(API调用/MCP服务/费用管理) + 千问开放平台(千问专卖店)
     ↓ 提供API/MCP服务
第三层 · 应用构建层 ✅已进驻(主力) + 待扩展
  百宝箱(AI应用工厂→支付宝小程序) + 通义平台(C端智能体,待进驻)
     ↓ 应用运行
第四层 · 基础设施层 ✅已进驻
  小程序云(支付宝小程序服务器) + 阿里云ECS/FC(深度定制,暂不需要)
     ↓ 触达用户
第五层 · 分发与变现层 部分进驻
  支付宝小程序(✅已进驻,C端业主) → 钉钉(待进驻,B端装修公司)
  → 支付宝开放平台(待进驻,支付/信用) → 阿里云云市场(远期,API变现)
     ↓ 知识沉淀(独立支线)
第六层 · 内容与知识管理层 待评估
  语雀(脱敏科普/SEO引流,核心库不放)

当前状态: 模型服务层 + 应用构建层 + 基础设施层已打通,分发层只走了支付宝小程序一条路。 下一步最低成本扩展: 去通义平台建一个C端智能体(零开发成本,多一个流量入口)。

---

相关文档

• 知设阿里生态进驻项目书 — 平台体系梳理、进驻策略、90天路线图
• 语雀安全评估与内容策略 — 安全深度分析、脱敏文章示例、平台对比