1. 为什么“Agency Agents”不是又一个AI Agent概念炒作？
最近在几个技术社区里，看到不少人在讨论“Agency Agents”这个词，有人把它等同于AutoGen的GroupChat，有人直接当成LangChain的AgentExecutor加了个复数后缀，还有人说这就是“多智能体协作”的新马甲。我跟几位做跨平台工具链集成的同行聊过，发现大家对这个词的理解偏差特别大——不是因为概念太难，而是因为没人愿意花时间去拆解它背后真实的工程约束。
“Agency Agents”这个提法，核心不在“Agent”上，而在“Agency”。Agency在软件工程语境里，指的是一种可委托、可代理、可问责的运行时契约能力。它不关心你用的是LLM还是规则引擎，也不限定你跑在本地还是云端，它只问三个问题：
- 这个实体能否被明确授权执行某类任务？
- 它的执行过程是否可被外部观察、中断或重定向？
- 当它出错或超时，是否有清晰的责任归属路径（比如回滚策略、日志溯源、状态快照）？
这和当前主流的单体Agent框架有本质区别。比如你用LangChain写一个“查天气+订咖啡+发邮件”的链式Agent，整个流程绑死在一个Python进程里，一旦中间环节失败，你得靠try/except硬扛，日志里只有一行“Exception in run()”，根本不知道是OpenWeather API超时了，还是Starbucks API返回了401，还是SMTP服务器拒绝了附件。而Agency Agents的设计起点，就是把这三个动作分别交给三个独立注册的Agent实例——每个都带自己的身份凭证、资源配额、健康探针和失败熔断策略。
关键词里虽然空着，但结合标题里的“跨平台”“AI编程”“生态”三个锚点，就能锁定它的实际落地场景：不是做Demo，而是支撑某高校实验室的AI辅助编程平台，让本科生能用自然语言描述需求，系统自动调度代码生成、单元测试生成、CI流水线触发、文档补全等不同能力模块；也不是服务单个IDE插件，而是要同时对接VS Code、JetBrains全家桶、Web IDE三类前端，还要兼容GitLab CI、GitHub Actions、自建K8s Job三种后端执行环境。
我试过用纯LLM函数调用模拟这种架构，结果在真实项目中崩得很快——模型幻觉导致Agent误判自身能力边界，比如把“生成Dockerfile”当成“部署到生产环境”，或者在没有K8s权限的沙箱里尝试调用kubectl。后来才明白，“Agency”真正的技术门槛，不在推理层，而在能力注册中心的设计、执行上下文的隔离机制、以及跨平台指令语义的标准化映射。这些细节，恰恰是大多数教程和开源项目刻意回避的“脏活”。
所以这篇不是讲怎么调API、怎么写prompt，而是还原我们团队在构建某跨平台系统时，如何从零开始定义Agent的“可委托性”、设计跨IDE的能力路由表、处理GitLab和GitHub在Job生命周期事件上的语义差异。所有方案都经过3个月真实项目压测，不是纸上谈兵。
2. Agency Agents的四层契约模型：比“角色”“工具”更底层的抽象
很多开发者一听到“多Agent”，第一反应是给每个Agent分配一个角色（Coder、Reviewer、Tester），再塞一堆工具（git、curl、pytest）。这在单机Demo里跑得通，但放到跨平台环境中，立刻暴露根本缺陷：角色是主观描述，工具是具体实现，而Agency需要的是可验证、可协商、可退订的客观契约。
我们最终落地的Agency Agents架构，基于四层契约模型，每一层都对应一个必须由工程手段保障的SLA（服务等级协议），而不是靠prompt约束：
2.1 能力契约（Capability Contract）：定义“你能做什么”，而非“你叫什么”
这是最常被忽略的一层。传统Agent框架里，能力往往通过函数签名体现，比如def generate_test_code(repo_path: str) -> str:。但问题在于：这个函数在VS Code插件里能调，在GitLab CI里却可能因缺少文件系统权限而失败；在本地开发环境返回JSON，在Web IDE里却要返回Base64编码的blob。
我们定义能力契约为一个YAML Schema，包含三个强制字段：
# capability.yaml id: "code/test/generate" version: "1.2.0" interface: input_schema: type: object properties: repo_url: type: string format: uri target_language: type: string enum: ["python", "javascript", "rust"] output_schema: type: object properties: test_files: type: array items: type: object properties: path: {type: string} content: {type: string} constraints: - "requires: git@v2.35+" # 依赖的底层工具版本 - "timeout: 120s" # 最长执行时间 - "memory_limit: 512MB" # 内存上限关键点在于：这个契约不绑定任何实现。VS Code插件可以用Node.js调用本地pytest，GitLab CI可以用Python容器执行相同逻辑，Web IDE可以调用后端API——只要它们都声明支持code/test/generate@1.2.0，前端就能无感切换。我们实测过，在某次GitLab Runner内存升级后，自动将所有测试生成任务从旧版容器（1.0.0）平滑迁移到新版（1.2.0），全程用户无感知。
提示：能力ID采用反向域名+语义路径，避免命名冲突。比如
ai.example.com/code/lint表示某公司内部的代码检查能力，和开源社区的org.langchain/lint天然隔离。
2.2 执行契约（Execution Contract）：定义“你在哪里做”，而非“你怎么做”
很多团队卡在这一步：以为把Agent部署到K8s就叫“跨平台”，结果发现VS Code插件调用时，Agent返回的路径是/app/workspace/main.py，而IDE只认file:///Users/xxx/project/main.py。根源在于混淆了“执行位置”和“能力语义”。
执行契约的核心是环境上下文声明，它告诉调度器：“我在什么条件下能可靠工作”。我们用JSON Schema描述，包含：
platform: 支持的宿主环境（vscode,jetbrains,webide,gitlab-ci,github-actions）runtime: 运行时要求（nodejs@18+,python@3.10+,container@docker）access_scope: 数据访问范围（workspace,git_repo,user_home,none）network_policy: 网络策略（allow_outbound,deny_outbound,allow_internal_only）
当用户在VS Code里发起“生成测试”请求时，调度器不是随机选一个Agent，而是做三件事：
- 解析请求中的能力ID（
code/test/generate@1.2.0） - 查询注册中心，筛选出所有声明支持该能力且
platform=vscode的Agent - 检查这些Agent的
access_scope是否包含workspace（因为测试生成需读取源码）
我们曾遇到一个坑：某JetBrains插件Agent声明了access_scope: git_repo，但实际执行时会扫描整个项目目录（包括node_modules）。上线前我们加了沙箱检测——用strace监控其系统调用，发现它偷偷打开了/usr/bin/find。最后强制要求所有Agent在注册时提交strace白名单，否则拒绝接入。
2.3 协作契约（Collaboration Contract）：定义“你和谁配合”，而非“你单独干啥”
单个Agent再强，也解决不了跨平台问题。真正的难点在于：当“代码生成Agent”产出PR后，“CI触发Agent”如何知道该触发哪个流水线？“文档生成Agent”怎么拿到刚合并的commit hash？
协作契约解决的就是事件语义对齐问题。我们不采用通用消息总线（如Kafka），因为不同平台的事件格式天差地别：
| 平台 | PR创建事件字段 | CI触发事件字段 |
|---|---|---|
| GitHub | pull_request.number,pull_request.head.sha | workflow_run.id,workflow_run.head_sha |
| GitLab | object_attributes.last_commit.id,object_attributes.target_branch | build_id,commit.id |
如果让每个Agent自己解析这些字段，维护成本爆炸。我们的方案是：定义统一的协作事件Schema，并由平台适配器负责转换。
例如，所有Agent只认这个标准事件：
{ "event_type": "pr_merged", "payload": { "repo_id": "example/project-a", "pr_number": 42, "merged_commit": "a1b2c3d4...", "base_branch": "main" } }GitLab适配器监听Merge Event，提取object_attributes.last_commit.id和object_attributes.target_branch，填充到标准Schema；GitHub适配器监听PullRequestEvent，提取pull_request.number和pull_request.merge_commit_sha。这样，CI触发Agent只需订阅pr_merged事件，完全不用关心上游是哪家平台。
实测效果：当某客户从GitHub迁移到GitLab时，我们只改了适配器配置，所有Agent代码零修改。
2.4 问责契约（Accountability Contract）：定义“出错了找谁”，而非“别出错”
这是Agency区别于普通Agent的终极标志。没有问责机制，所谓“生态”就是一盘散沙。
问责契约包含三要素：
- 责任主体标识：每个Agent注册时必须提供唯一
agent_id（如ci-trigger-gitlab-prod-v2），不能是随机UUID - 操作审计日志：所有输入/输出必须经由统一日志网关，字段包括
agent_id,request_id,timestamp,input_hash,output_hash - 失败处置策略：声明
retry_policy（最多重试2次）、fallback_agent（降级到ci-trigger-fallback）、alert_threshold（连续3次超时告警）
我们曾在线上遇到一个诡异问题：某次大规模PR合并后，CI触发成功率从99.8%掉到87%。通过日志网关按agent_id聚合，发现ci-trigger-gitlab-prod-v2的失败率飙升，但input_hash完全一致。进一步查output_hash，发现它返回的workflow_run.id是空字符串——原来GitLab API在高负载时返回了202 Accepted但没写入DB。我们立刻启用fallback_agent，它改用轮询方式确认流水线启动，成功率回升。第二天，运维团队扩容了GitLab Runner，问题根除。
注意：问责契约不是为了追责，而是为了快速定位故障域。我们禁止在日志里记录原始输入（防敏感信息泄露），只存SHA256哈希值。
3. 跨平台能力路由：如何让VS Code的请求精准抵达GitLab CI上的Agent
很多人以为“跨平台”就是写个HTTP API，让所有前端调用。但真实场景远比这复杂：VS Code插件运行在用户本地，需要低延迟响应；Web IDE运行在浏览器，只能发HTTPS请求；GitLab CI运行在内网，根本无法被外部访问。如果强行用统一API，要么牺牲安全性（开放内网端口），要么牺牲性能（所有请求走代理）。
我们的解决方案是双向通道+声明式路由，核心思想：不追求“所有平台都能调用同一个地址”，而是让每个平台只和自己信任的Agent通信，由中央路由表协调协作关系。
3.1 双向通道架构：本地Agent与远程Agent的握手协议
我们为每类平台设计专属通信通道：
| 平台类型 | 通道类型 | 特点 | 示例 |
|---|---|---|---|
| 桌面IDE（VS Code/JetBrains） | WebSocket长连接 | 低延迟、支持双向推送 | 插件启动时连接wss://router.example.com/vscode/agent-id |
| Web IDE | HTTP REST + Server-Sent Events | 兼容浏览器安全策略 | POST /webide/trigger+GET /webide/events |
| CI/CD（GitLab CI/GitHub Actions） | Webhook回调 | 无需维持连接，适合短时任务 | GitLab配置https://router.example.com/gitlab/webhook |
关键创新在于：所有通道都支持“能力声明”和“心跳保活”。以VS Code插件为例，它连接后立即发送：
{ "type": "register_capability", "payload": { "agent_id": "code-gen-vscode-local-v1", "capabilities": ["code/generate@1.0.0", "code/refactor@1.1.0"], "platform": "vscode", "health_check": "/health" } }路由中心收到后，将其加入能力索引，并定期调用/health（超时3秒则标记为离线）。这样，当Web IDE用户请求“生成代码”时，路由中心知道：VS Code插件有能力处理，但用户当前没打开VS Code——于是它不会傻等，而是触发降级流程：调用远程的code-gen-cloud-v2Agent。
3.2 声明式路由表：用YAML定义“谁在什么条件下接活”
路由逻辑不写在代码里，而是用YAML配置，支持热更新。这是我们的生产环境路由表片段：
# routes.yaml - name: "code_generation_route" trigger_event: "user_request.code_generate" conditions: - platform: "webide" priority: 1 - platform: "vscode" priority: 2 online_check: true # 必须在线才选 candidates: - agent_id: "code-gen-webide-cloud-v3" weight: 0.7 constraints: - "memory_limit <= 1GB" - agent_id: "code-gen-vscode-local-v1" weight: 0.3 constraints: - "access_scope == workspace" - name: "ci_trigger_route" trigger_event: "pr_merged" conditions: - repo_owner: "enterprise-team" priority: 1 - repo_owner: "open-source" priority: 2 candidates: - agent_id: "ci-trigger-gitlab-prod-v2" weight: 1.0 constraints: - "platform == gitlab-ci"这里的关键设计：
- 优先级（priority）：不是简单的if-else，而是分层过滤。先按
platform分组，再在组内按online_check筛选，最后按weight加权选择。 - 约束（constraints）：动态表达式，由轻量级解释器执行（我们用goja，JS引擎，启动快、内存小）。
- 权重（weight）：支持灰度发布。比如新上线
code-gen-cloud-v3，先设weight: 0.05，观察错误率，再逐步提升。
我们曾用这个机制完成一次零停机升级：将ci-trigger-gitlab-prod-v2的流量从100%逐步切到ci-trigger-gitlab-prod-v3，全程监控error_rate指标，当v3的错误率超过v2的1.2倍时自动回滚。
3.3 上下文透传：如何让GitLab CI上的Agent知道“这是来自VS Code的请求”
跨平台协作最大的陷阱，是丢失上下文。比如VS Code用户点击“生成测试”，这个请求经过路由中心转发给GitLab CI上的Agent，但Agent只知道要生成测试，不知道：
- 用户在VS Code里打开了哪个文件（影响测试覆盖率分析）
- 用户的编辑器主题是深色还是浅色（影响生成的Markdown预览样式）
- 用户之前是否禁用了某个规则（如
no-console）
我们的方案是：所有跨平台调用，必须携带标准化的Context Header，由前端SDK自动注入：
| Header名 | 含义 | 示例值 |
|---|---|---|
X-Agent-Source | 请求发起方 | vscode-extension/2.4.1 |
X-User-Workspace | 工作区标识 | sha256:abc123...（工作区路径哈希） |
X-Editor-Theme | 编辑器主题 | dark-plus |
X-Request-ID | 全局追踪ID | req-7f8a2b3c-... |
GitLab CI Agent收到请求后，解析X-Agent-Source，就知道该启用VS Code专用的代码风格模板；读取X-User-Workspace，就能从对象存储里拉取该用户的个性化配置（如.testrc.json）。我们甚至用X-Editor-Theme动态调整生成的HTML报告CSS——深色主题下用#1e1e1e背景，浅色主题用#ffffff。
实测数据：上下文透传使跨平台任务的首次成功率从76%提升到93%，因为Agent不再需要猜用户意图。
4. 工程实践：从零搭建Agency Agents注册中心的七步踩坑实录
光有理论不够，我来还原我们搭建Agency Agents注册中心的真实过程。这不是教科书式的“第一步安装Docker”，而是记录每一个让我们加班到凌晨的坑，以及最终落地的务实方案。
4.1 第一步：选型——为什么放弃Consul/Etcd，选择自研轻量注册中心
初期我们对比了Consul、Etcd、Nacos，结论很明确：它们都是为微服务设计的，不是为AI Agent设计的。
问题出在“健康检查”上。微服务的健康检查是HTTP GET/health，返回200就认为OK。但Agent的健康是动态的：
- VS Code插件Agent可能因用户关闭IDE而失联，但进程还在
- GitLab CI Agent每次执行都是新容器，健康状态只存在几分钟
- Web IDE Agent受浏览器限制，WebSocket连接可能被防火墙静默断开
我们试过用Consul的TTL健康检查（每30秒上报一次），结果注册中心里堆满了僵尸Agent——因为网络抖动导致上报失败，Consul就把Agent标记为failed，但Agent其实还活着。
最终方案：自研基于Redis的注册中心，核心只有两个数据结构：
agents:{agent_id}：Hash，存Agent元数据（last_heartbeat,capabilities,platform）capabilities:{capability_id}：Sorted Set，按score（=last_heartbeat时间戳）排序，方便查询最新活跃Agent
心跳机制改为：Agent每10秒发一次HSET agents:{id} last_heartbeat {unix_ts}，注册中心后台用ZRANGEBYSCORE capabilities:{cap} -inf {now-60}清理60秒未心跳的Agent。简单、高效、可控。
教训：不要迷信成熟组件。AI Agent的生命周期特征（短时、高动态、多态）决定了必须定制基础设施。
4.2 第二步：能力发现——如何让Web IDE快速找到“可用的代码生成Agent”
能力发现不是简单的“查数据库”，而是实时匹配。用户在Web IDE里输入“用React写一个计数器”，系统要1秒内返回：
- 哪些Agent支持
code/generate@1.2.0 - 它们当前是否在线
- 它们的负载情况（CPU、内存、队列长度）
- 是否满足用户约束（如“必须支持TypeScript”）
我们设计了三级缓存：
- L1：本地内存缓存（Go
sync.Map）：存最近1分钟的查询结果，TTL 10秒。应对突发流量。 - L2：Redis缓存：存能力索引，Key为
cap_index:code/generate@1.2.0，Value为JSON数组["agent-id-1", "agent-id-2"]。TTL 60秒，由后台定时刷新。 - L3：冷数据源：PostgreSQL，存Agent完整元数据。只在缓存失效或管理后台查询时使用。
关键优化：L2缓存的Key包含约束条件哈希。比如用户要求typescript=true，Key就是cap_index:code/generate@1.2.0:ts-true。这样不同约束的查询互不干扰，避免缓存污染。
实测：在1000并发下，95%的查询在3ms内返回，峰值QPS达12,000。
4.3 第三步：安全沙箱——如何防止Agent“越权”读取用户文件
这是最危险的环节。VS Code插件Agent如果被恶意prompt诱导，可能执行cat ~/.ssh/id_rsa。我们必须确保：
- Agent只能访问用户明确授权的工作区目录
- 不能执行任意shell命令
- 不能访问网络（除非显式声明
network_policy: allow_outbound）
我们的沙箱方案分三层：
- OS层：Linux user namespace + chroot。每个Agent进程运行在独立user namespace，root UID映射为非特权UID，chroot到工作区目录。
- 语言层：Node.js Agent用
vm2沙箱，禁用require、process、global等危险对象；Python Agent用restrictedpython，编译时移除__import__、exec等。 - API层：所有Agent必须通过SDK调用能力，SDK内置权限检查。比如
read_file(path)会校验path是否在workspace_root下，否则抛异常。
我们做过渗透测试：给Agent喂{"command": "require('child_process').execSync('cat /etc/passwd')}"，结果vm2直接报错ReferenceError: require is not defined，连沙箱都没逃出去。
4.4 第四步：日志与追踪——如何用1%的开销实现100%的操作可观测
可观测性不是锦上添花，而是Agency的基石。没有它，你永远不知道是Agent错了，还是网络错了，还是用户输错了。
我们采用“轻量埋点+中心聚合”模式：
- Agent侧：只记录4个字段（
agent_id,request_id,timestamp,status），用UDP发到日志网关（无连接、低开销）。 - 网关侧：接收UDP包，解析后写入Kafka（保证顺序），再由Flink作业 enriched：关联
request_id补全输入/输出哈希、添加平台信息、计算耗时。 - 存储侧：Elasticsearch，索引按天滚动，保留30天。关键查询如
SELECT * FROM logs WHERE agent_id='ci-trigger' AND status='error' ORDER BY timestamp DESC LIMIT 100，毫秒级响应。
成本控制：Agent侧日志体积<1KB/请求，网关处理延迟<50ms，集群资源占用<2核CPU/天。
4.5 第五步：降级与熔断——当GitLab CI Agent集体失联时怎么办
高可用不是“不挂”，而是“挂了也能继续干活”。我们设计了三级降级：
- 一级降级（自动）：当某类Agent在线率<30%，自动切换到
fallback_agent（如用云上Agent替代本地Agent）。 - 二级降级（半自动）：当
fallback_agent错误率>5%，触发告警，人工确认后启用manual_override模式——路由中心返回{"status":"pending","message":"请稍后查看CI状态"}，用户界面显示“已提交，正在排队”。 - 三级降级（手动）：运维在管理后台强制指定
override_route，将所有pr_merged事件导向备用GitLab Runner集群。
熔断策略基于滑动窗口：统计最近60秒的请求，若错误率>20%且请求数>10，则对该Agent熔断30秒。熔断期间，所有请求直接返回503 Service Unavailable，避免雪崩。
上线首月，我们经历了3次GitLab API波动，全部由一级降级自动恢复，平均恢复时间8.2秒。
4.6 第六步：版本演进——如何让老版Agent和新版Agent和平共处
能力版本不是简单的v1v2，而是涉及语义兼容性。比如code/generate@1.2.0新增了test_coverage字段，但1.1.0的Agent不认识它，直接忽略还是报错？
我们的版本策略：
- PATCH版本（1.2.1 → 1.2.2）：向后兼容，只修复bug。Agent可无缝升级。
- MINOR版本（1.2.0 → 1.3.0）：向后兼容，新增可选字段。路由中心自动剥离未知字段。
- MAJOR版本（1.2.0 → 2.0.0）：不兼容，必须显式声明。路由中心拒绝转发，返回
400 Bad Request并提示“请升级客户端”。
关键实现：路由中心维护一个compatibility_matrix.yaml：
- from: "code/generate@1.2.0" to: "code/generate@1.3.0" compatibility: "backward" transform: | if !input.test_coverage { delete input.test_coverage; } - from: "code/generate@1.2.0" to: "code/generate@2.0.0" compatibility: "none"这样，当用户用旧版SDK调用2.0.0能力时，路由中心直接拦截，避免Agent崩溃。
4.7 第七步：监控告警——哪些指标真正值得盯，而不是刷存在感
我们砍掉了所有“好看但无用”的指标（如CPU使用率），只监控5个黄金信号：
| 指标 | 计算方式 | 阈值 | 告警动作 |
|---|---|---|---|
agent_online_ratio | 在线Agent数 / 总注册数 | <80% | 检查网络、心跳服务 |
route_success_rate | 成功路由请求数 / 总请求数 | <95% | 检查路由表、能力注册 |
capability_match_rate | 匹配到Agent的请求数 / 总请求数 | <90% | 检查能力覆盖、约束条件 |
fallback_activation_rate | 降级请求数 / 总请求数 | >5% | 检查主力Agent健康度 |
context_header_missing_rate | 缺少X-Request-ID的请求数 / 总请求数 | >1% | 检查前端SDK集成 |
所有指标用Prometheus采集，Grafana看板，告警通过企业微信机器人直达值班人。我们设置了一个“静默期”：新Agent上线后2小时不告警，让它先热身。
上线三个月，平均每天收到2.3条有效告警，全部在15分钟内定位根因。没有一次是“CPU 95%”这种无效告警。
5. 真实项目复盘：某高校AI编程平台的落地挑战与破局点
最后分享一个完整项目案例，还原Agency Agents如何从理论走进现实。这不是PPT里的成功学，而是带着血丝的实战笔记。
5.1 项目背景：一个被低估的教育场景
某高校计算机系想建AI编程辅助平台，目标很朴素：让大二学生用自然语言描述算法题（如“写一个快速排序，要求原地排序，时间复杂度O(n log n)”），系统自动生成代码、测试用例、运行演示。难点在于：
- 学生用VS Code、PyCharm、Web IDE三种环境
- 代码生成需在安全沙箱执行（防恶意代码）
- 测试需在隔离环境运行（防
os.system("rm -rf /")） - 演示需实时渲染（Web IDE里直接看到排序动画）
他们最初找了一家AI公司，方案是：一个大模型API，前端直接调。结果上线一周就崩了——学生用中文提问，模型返回英文注释；学生要求“用Java”，模型生成了Python；最严重的是，有学生输入"public class Test { static { Runtime.getRuntime().exec(\"rm -rf /tmp\"); } }"，模型真把它当代码执行了。
5.2 破局点一：用Agency解耦“理解”与“执行”
我们没碰大模型，而是把问题拆成三层：
- 理解层：用轻量微调模型（DistilBERT）做意图识别，输出结构化指令（
{"action":"generate_code", "language":"java", "algorithm":"quicksort", "constraints":["inplace"]}） - 路由层：Agency注册中心，根据
language和constraints匹配Agent - 执行层：Java代码生成Agent（运行在Docker沙箱）、测试生成Agent（运行在独立JVM）、动画渲染Agent（Node.js + Canvas）
这样，即使大模型出错（比如把quicksort识别成mergesort），也只是影响理解层，执行层依然安全。我们实测，模型误识别率23%，但最终生成正确代码率仍达89%，因为执行层有强校验：生成的Java代码必须通过javac -source 11 -target 11编译，且junit-platform-console能跑通测试。
5.3 破局点二：用协作契约解决“演示动画”这个魔鬼需求
“实时渲染排序动画”看似简单，实则是跨平台地狱。VS Code里用Webview加载HTML；PyCharm里用JavaFX；Web IDE里用Canvas。如果让每个Agent自己实现，维护成本爆炸。
我们的方案：定义协作事件animation_frame，Schema如下：
{ "event_type": "animation_frame", "payload": { "frame_id": 123, "data": [ {"index": 0, "value": 5, "state": "comparing"}, {"index": 1, "value": 2, "state": "swapping"}, {"index": 2, "value": 8, "state": "idle"} ], "timestamp_ms": 1712345678901 } }然后为每个平台写一个极简的“动画播放器”：
- VS Code：Webview里用
requestAnimationFrame渲染SVG条形图 - PyCharm：JavaFX
BarChart绑定ObservableList - Web IDE：Canvas
fillRect画像素块
所有Agent只管发animation_frame事件，播放器只管收事件渲染。我们用1天就完成了三端动画支持，而客户原计划是3周。
5.4 破局点三：用问责契约建立师生信任
老师最担心的是：学生抄AI代码，怎么证明是他自己写的？我们把问责契约做到极致：
- 每次代码生成，记录
student_id,assignment_id,request_text_hash,generated_code_hash - 所有日志加密存证，不可篡改
- 教师后台可查：“张三在第3次提交时，AI生成了
QuickSort.java，原始提示为‘用Java写快排’，生成代码与标准答案相似度82%”
上线后，老师反馈：“现在我能看清学生哪里卡住了，是算法理解问题，还是语法问题，还是AI误导问题。”
5.5 关键数据与反思
- 性能：从输入到代码生成，P95延迟<1.8秒（含网络）
- 稳定性：连续90天无重大故障，平均MTBF 127小时
- 扩展性：从首发3个Agent（生成、测试、动画），6个月内扩展到17个（含代码审查、复杂度分析、UML生成）
- 教训：最大的坑不是技术，而是文档同步。我们要求每个Agent必须提交
capability.yaml和README.md，但总有开发者漏更新。最后强制CI检查：capability.yaml变更必须伴随README.md更新，否则PR不通过。
Agency Agents的价值，从来不在炫技，而在于把AI的不确定性，框进工程的确定性里。它不承诺100%正确，但承诺100%可追溯、可替换、可问责。当你下次看到“多智能体”这个词，不妨多问一句：它的Agency在哪？
