@siweimofang

zhishe-a2a

Name: zhishe-a2a
Availability: InStock
Author: siweimofang

知设AI装修顾问 - 主仓库(知识库+DSH插件+GEO)

Stars: 0
Language: Python
Created: Aug 22, 2026
Updated: Aug 22, 2026

Workspace

GitHub repo

Introduction

知设 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。

关键端点

端点	作用	验证命令
`GET /`	服务元信息	`curl http://127.0.0.1:8765/`
`GET /.well-known/agent.json`	AgentCard(千问发现 Agent)	`curl http://127.0.0.1:8765/.well-known/agent.json`
`POST /a2a/message/send`	主路径 - JSON-RPC 同步调用	`python examples\client_basic.py`
`POST /a2a/message/stream`	SSE 流式(V1.0 返回 -32601)	—
`GET /health/ready`	LLM 就绪检查	`curl http://127.0.0.1:8765/health/ready`

配置文件 `.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 实测)

项	结果
服务启动	✅ PID 26520,端口 8765 监听中
`GET /`	✅ HTTP 200
`GET /.well-known/agent.json`	✅ 返回完整 AgentCard,3 个 skill
`examples\client_basic.py` 真对话	✅ DeepSeek 正常返回"沈阳 90 平半包"详细回复
`pytest tests/`	✅ 28 passed in 14s
`.env` 新 Key 已生效	✅ 头 `DEEPSEEK_API_KEY=sk-`,尾 `f2cd1fac7bc5`

项目结构

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       # 运行日志

千问管控台接入流程

阿里云百炼管控台 → 「三方 Agent」管理
点"接入三方 Agent"
填 https://你的域名/.well-known/agent.json
配 AgentCard 详情(自动发现)
千问按 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 更新)

项	状态
A2A 协议端点能响应	✅
AgentCard 千问能解析	✅(3 skills,符合 A2A 0.2.5)
千问发消息 → 收到 Agent 回复(端到端)	✅(DeepSeek 真回话已验证)
`.env` 新 Key 已轮换	✅
协议层 + AgentCard 测试覆盖	✅ 28 passed
响应延迟 < 8s(p95)	⏳ 待压测
100 次对话 0 报错	⏳ 待压测
流式 SSE 端点	❌ V1.0 不实现,返回 -32601
`services/llm` 路径问题	✅ 实际为 `app/services/llm.py`,与 server 引用一致

内容安全与三层存储策略

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

三层存储架构

层级	内容	存储位置	发布渠道	原因
L1 · 核心库	Gotchas 532条实战经验、独家分析框架	本地 `data/knowledge.json` + Git	仅百宝箱知识库	核心资产,零外泄风险
L2 · 脱敏科普	基于国标的避坑知识、施工规范解读	本地 Markdown 源文件	语雀 / 微信公众号	SEO引流,展示专业度
L3 · 内部文档	产品规划、用户反馈分析、运营数据	飞书文档 / Notion	不公开	团队协作,权限可控

脱敏规则

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

平台安全对比

平台	模型训练风险	私有内容保护	知设用途
语雀(蚂蚁)	🟡 中等(协议模糊)	🟢 较好	仅放脱敏科普
飞书(字节)	🟢 较低(明确承诺不训练)	🟢 好	内部文档协作
Notion(美国)	低(明确声明不训练)	🟢 好	个人知识管理
知乎	🔴 较高(用内容训练过模型)	🔴 差(全部公开)	不建议放核心内容
微信公众号(腾讯)	中等	—	脱敏科普引流
本地Markdown+Git	🟢 无风险	🟢 完全控制	核心库最佳存储

阿里生态平台关系

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

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