第 18 章：工程实践：从零构建业务智能体

本章为实践章，给出基于本书原理的落地路径。代码是主要的交流语言，因此本章以代码与操作步骤为主，原理见前文相应章节。

18.1 实现自定义智能体

from prog.runtime.base_agent import BaseAgent, AgentResponse

class GreetingAgent(BaseAgent):
    def __init__(self):
        super().__init__(agent_name="问候Agent", agent_type="greeting")

    def process(self, user_input, context):
        return AgentResponse(content=f"您好！我是{self.agent_name}，很高兴为您服务。",
                             agent_name=self.agent_name)

agent = GreetingAgent()
resp = agent.process("你好", {"user": {}})
print(resp.content)

18.2 注册路由与上下文注入

from prog.runtime.coordinator import CoordinatorAgent

coordinator = CoordinatorAgent(
    agents={"greeting": greeting_agent},   # 业务通道：按 intent.target_agent 查找
    knowledge_assistant=greeting_agent,    # 咨询通道：兜底
)
routed = coordinator.route(
    "你好，帮我查一下今天的安排",
    {"user": {"role": "manager"}, "history": [], "data": {}},
)

业务接入时替换路由表为自身业务路由，业务规则以 BaseRule 子类 + RuleRegistry.register() 提供。

18.3 接入业务规则的完整路径

1. 继承 BaseRule 实现业务规则（设置 rule_name / is_hard / spec_ref / rule_type，实现 check()）并注册；
2. 继承 BaseAgent 实现领域智能体（设置 agent_name / agent_type / applicable_rules，重写 process() 或复用默认生命周期）；
3. 实例化 CoordinatorAgent 并替换路由表；
4. 可选注入 llm_provider / database / audit_log_dal（未注入降级模式运行）；
5. 高风险操作接入七层审核链，权限接入 PermissionSystem，安全接入 AgentSecurity，模块隔离接入 @require_module。

接入顺序本身遵循第 8 章原理：先让框架在降级模式跑通流程（验证正确性），再逐项注入真实依赖（接入能力）。

18.4 框架内嵌模块约定

prog/runtime/ 为框架本体（绳墨 Runtime），仅随本仓库维护；框架与业务共用同一仓库、统一以 prog.runtime.* 导入。原「开源独立副本 + 业务副本」双副本模式已取消，不再存在跨仓库同步义务；框架变更仅需修改本仓库 prog/runtime/ 自身。

原理： 框架内嵌于业务仓库后，"主运行 + 冷备用"的同步约束随之解除：不再维护可审计、可验证的框架快照，也无副本漂移成"另一套代码"的风险；框架改动直接作用于运行代码，回归由本仓库测试体系覆盖。

18.5 测试策略

# 框架自检（覆盖智能体/规则引擎/审核链/权限/安全/模块开关/意图识别）
python tests/test_framework.py

# 接口兼容性回归（核对 API_SPEC 兼容性基线）
python -m pytest tests/

原理： 框架可在无 LLM / 无数据库的 CI 中全量测试（降级模式），这是第 8.5 节"最小可信实现"的工程收益——正确性验证不依赖外部能力。接口兼容性回归把"版本演进不破坏下游"制度化：每一次改动都要回答"接口是否向后兼容"。

18.5.1 三步运营验收法（功能类）

单元测试与接口回归不足以证明"一套系统能真的用起来"。真实项目采用"三步运营模拟"来验收业务闭环：

1. 组织初始化：用业务流程建立部门与岗位账户（HR 建档、总经理审批），验证组织树完整、角色就位、全员可登录；
2. 部门内流程：各业务部门训练内部流程充分，逐条"训练 → 审批 → 生效 → 发起 → 审批 → 落库"闭环；
3. 跨部门端到端：训练跨部门流程，跑通"订单 → 计划 → 采购 → 生产 → 质检 → 入库 → 发货 → 回款"全链协同。

判定要点：写操作成功须同时具备"成功语义 + 落库业务凭证（单号/审批号）"二者缺一不可（避免纯描述或中间态误判）；业务数据全部经正常流程建立（数据自建），空数据友好引导视为通过而非缺陷；遇识别错误先对话修正或训练覆盖，经判断确属代码失误（训练入口缺失、正则误伤等）才改代码。

18.5.2 自动化端到端的六条铁律

大规模端到端回归的实况沉淀出几条自动化原则：

1. 登录只在数据准备阶段发生一次，业务路径复用令牌——登录接口按 IP 限流，业务用例每步重新登录会触发限流，导致后段雪崩全失败；
2. 判定必须以数据库落库为准——回复里出现"已成功"并不等于真的写入业务表，直查落库验证可防假通过；
3. 话术"首轮无歧义词"——易被高优先级识别规则吞掉的词放到后续轮次补齐，靠多轮状态沿用意图；
4. 改规则配置后须重启——配置有进程级缓存，热更新可能仍读旧值；
5. 会话隔离——同一账号跨用例要重置会话，防历史上下文污染导致意图识别漂移；
6. 失败先归类再处置——按"意图跑偏 / 数据缺失 / 判定口径 / 真实缺陷"分类，多数走训练修正，少数才是代码缺陷。

18.6 常见设计问题

18.7 工程验收清单

专家级工程评审以验收清单收尾。按本书原理逐项核对，可作为项目上线前的门禁：

原理： 验收清单是"原理的可操作化"——每一验收项都对应一个设计原则，使评审从"凭感觉"变为"逐项核对"。清单本身也应随框架演进更新（如新增机制时补充对应验收项），保证验收与设计同步。