tw2/qingjian_cs/DEVELOPMENT_RULES.md

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. 禁止无日志的关键动作。

---

执行口令（开发前先读一遍）：

• 先工具化，再智能体化，最后才是话术优化。
• 决策结构化，执行单一化，状态持久化。