jimi
a842f1861f
Some checks failed
Pre-commit / run (ubuntu-latest) (push) Has been cancelled
Deploy Sphinx documentation to Pages / build_en (ubuntu-latest, 3.10) (push) Has been cancelled
Deploy Sphinx documentation to Pages / build_zh (ubuntu-latest, 3.10) (push) Has been cancelled
Python Unittest Coverage / test (macos-15, 3.10) (push) Has been cancelled
Python Unittest Coverage / test (macos-15, 3.11) (push) Has been cancelled
Python Unittest Coverage / test (macos-15, 3.12) (push) Has been cancelled
Python Unittest Coverage / test (ubuntu-latest, 3.10) (push) Has been cancelled
Python Unittest Coverage / test (ubuntu-latest, 3.11) (push) Has been cancelled
Python Unittest Coverage / test (ubuntu-latest, 3.12) (push) Has been cancelled
Python Unittest Coverage / test (windows-latest, 3.10) (push) Has been cancelled
Python Unittest Coverage / test (windows-latest, 3.11) (push) Has been cancelled
Python Unittest Coverage / test (windows-latest, 3.12) (push) Has been cancelled
105 lines
3.8 KiB
Markdown
105 lines
3.8 KiB
Markdown
# Qingjian CS 开发规则（强制）
|
||
|
||
> 目标：始终按 AgentScope 官方范式开发，避免系统再次回到“规则堆砌+难维护”的状态。
|
||
|
||
## 0. 总原则
|
||
|
||
1. 框架负责智能决策与编排，业务代码负责数据与动作执行。
|
||
2. 任何新需求，优先扩展工具和状态，不优先扩展 prompt 文本。
|
||
3. WebSocket 层只做收发与调度，不写业务判断。
|
||
|
||
## 1. 架构强约束
|
||
|
||
1. 必须使用 `ReActAgent + Toolkit + structured_model`。
|
||
2. 禁止在主流程里堆大量 `if/elif` 做业务决策。
|
||
3. 所有业务决策必须输出标准动作：`reply / quote / transfer / noop / update_state`。
|
||
4. 执行层只消费动作，不反推业务意图。
|
||
|
||
## 2. 分层规则
|
||
|
||
1. `client.py`：仅处理连接、收发、防抖、调度。
|
||
2. `brain/*.py`：只做 Agent 决策，不做 IO。
|
||
3. `tools/*.py`：封装业务能力（报价、风控、售后、客户画像、订单）。
|
||
4. `store/*.py`：数据库读写，禁止在 Agent 里写 SQL。
|
||
5. `rules.py`：仅保留少量硬约束与 prompt 基线，不承载复杂流程。
|
||
|
||
## 3. Tool First（工具优先）
|
||
|
||
新增需求必须先回答：
|
||
1. 这个能力是否应成为 tool 函数？
|
||
2. 输入输出是否可结构化？
|
||
3. 是否可复用给多个 Agent？
|
||
|
||
若答案为是，先建 tool，再改 agent。
|
||
|
||
## 4. 多 Agent 规范
|
||
|
||
1. 路由 Agent：只分发，不直接处理细节。
|
||
2. 报价 Agent：调用图片/尺寸/历史价工具后输出报价动作。
|
||
3. 售后 Agent：基于状态机推进流程。
|
||
4. 风控 Agent：输出风险等级与拦截建议。
|
||
5. Agent 间通信必须走结构化字段，禁止自由文本串联。
|
||
|
||
## 5. 数据库规范
|
||
|
||
必须落库：
|
||
1. 会话状态（当前阶段、最后动作、最后回复）。
|
||
2. 报价记录（图、尺寸、复杂度、价格、时间、操作人）。
|
||
3. 售后工单（状态流转、超时节点、责任人）。
|
||
4. 客户画像（退款率、未付款率、黑名单/备注）。
|
||
|
||
禁止：
|
||
1. 用内存 dict 作为长期状态真值。
|
||
2. 关键流程无持久化。
|
||
|
||
## 6. 回复质量规范
|
||
|
||
1. 优先自然、短句、口语化。
|
||
2. 禁止连续重复同语义句。
|
||
3. 先承接，再引导，再动作。
|
||
4. 客户无意义短句也要给最小承接。
|
||
5. 外部联系方式请求必须站内引导。
|
||
|
||
## 7. 风控规范
|
||
|
||
1. 地图/政治/黄暴等高风险必须先风控，再决定 reply/transfer。
|
||
2. 风控结果必须可审计（记录原因与触发信号）。
|
||
3. 不允许绕过风控直接外发。
|
||
|
||
## 8. 代码规模规范
|
||
|
||
1. 单文件建议 <= 500 行，超过必须拆分。
|
||
2. 新增功能默认新模块，不在老文件硬塞。
|
||
3. 重复逻辑出现第二次必须提取函数/工具。
|
||
|
||
## 9. 日志与可观测性
|
||
|
||
1. 每次动作必须有活动日志：`trace_id/customer_id/event/result`。
|
||
2. 关键节点必须可追踪：入站、决策、工具调用、出站、失败。
|
||
3. 错误日志必须包含可复现上下文（脱敏后）。
|
||
|
||
## 10. 测试与发布
|
||
|
||
1. 每次改动至少覆盖：打招呼、发图、询价、售后、转人工、风险场景。
|
||
2. 新增规则必须加回放样例（golden case）。
|
||
3. 未通过关键回放，不允许合入。
|
||
|
||
## 11. 变更流程（每次开发都执行）
|
||
|
||
1. 先写：需求 -> 动作模型 -> 工具接口 -> 状态变更。
|
||
2. 再写代码：tool -> agent -> orchestrator -> storage。
|
||
3. 最后验证：回放测试 + 日志检查 + 重复回复检查。
|
||
|
||
## 12. 禁止事项
|
||
|
||
1. 禁止把复杂业务塞进单个 prompt 企图一次性解决。
|
||
2. 禁止继续扩张“关键词硬编码回复库”。
|
||
3. 禁止把数据库逻辑散落在 websocket/client 层。
|
||
4. 禁止无日志的关键动作。
|
||
|
||
---
|
||
|
||
执行口令（开发前先读一遍）：
|
||
- 先工具化，再智能体化，最后才是话术优化。
|
||
- 决策结构化，执行单一化，状态持久化。
|