基于三省六部制构建可控AI多智能体协作框架Edict-平芜编程栈

1. 项目概述：当AI遇见三省六部

最近在折腾AI多智能体（Multi-Agent）协作，试过CrewAI、AutoGen这些主流框架，总感觉差点意思。它们像是一群没有领导的散兵游勇，把任务丢进去，让AI们自己“聊”，最后给你一个结果。至于中间发生了什么？质量如何控制？某个环节卡住了怎么办？你基本两眼一抹黑。这种“黑盒式”的协作，对于个人玩玩还行，一旦想用在稍微严肃点的场景，比如代码审查、项目规划，心里就完全没底。

直到我把目光投向了历史书。1300多年前，中国唐朝完善了一套中央官制——三省六部制。中书省出令，门下省审核，尚书省执行，六部各司其职。这套制度的核心不是效率至上，而是分权制衡与流程可控。一个政令从提出到执行，必须经过规划、审核、派发、执行、回报的完整闭环，每个环节权责清晰，且有专门的机构（门下省）负责挑刺和驳回。

我就在想，为什么不能把这套历经千年考验的“操作系统”搬到AI协作里来？于是，就有了Edict（圣旨）这个项目。它不是一个简单的Agent集合，而是一个制度化的AI协作架构。我用12个具有明确职责的AI Agent，分别扮演太子、三省（中书、门下、尚书）及六部+吏部的角色，构建了一个权责清晰、流程可视、结果可控的协作体系。

它解决了什么核心痛点？简单说，就是把AI协作从“放羊”变成了“上朝”。你作为“皇上”，下一个旨意（任务）。太子负责接旨和初步分拣，中书省负责拆解规划，门下省负责审核方案质量，尚书省负责调度派发，六部（户、礼、兵、刑、工、吏）并行执行专项任务。整个过程在一个叫“军机处”的实时看板里一目了然，你可以随时叫停、干预、查看每个Agent的“思考过程”。结果不再是不可追溯的黑盒，而是一份份结构清晰的“奏折”。

适合谁？如果你受够了传统Multi-Agent框架的不可控和调试困难，想找一个更稳健、更透明、更适合处理复杂链式或并行任务的开源方案，或者单纯对用历史智慧解决现代技术问题感兴趣，那么Edict值得你花时间了解一下。它基于OpenClaw构建，但理念是普适的。

2. 核心架构设计：分权制衡的AI朝廷

Edict的整个设计哲学都源于“制度优于自由协作”。现代AI框架强调Agent的自主性和灵活性，但这在复杂任务中往往导致混乱。Edict反其道而行之，用明确的角色、严格的流程和可视化的监控，构建了一个稳定可靠的协作系统。

2.1 十二部制Agent角色体系

这是整个系统的基石。每个Agent都不是通用的“AI助手”，而是有明确人设、职责和技能边界的“官员”。

太子 (taizi)：消息网关与过滤器。所有外部指令（通过飞书、Telegram等）首先到达太子。它的核心职责是分拣：如果是闲聊，直接调用知识库回复；如果是正经的“旨意”（任务），则进行提炼，生成规范的标题和摘要，并创建任务卡进入流程。这避免了无意义的会话消耗Token和干扰主流程。
三省：构成决策与审核核心。
- 中书省 (zhongshu)：规划中枢。接旨后，负责理解全局需求，并将宏大的旨意拆解成具体、可执行的子任务。例如，“开发一个用户系统”会被拆解为“设计数据库Schema”、“编写注册API”、“实现JWT鉴权”、“编写测试用例”等。
- 门下省 (menxia)：质量守门员。这是Edict区别于其他框架的杀手锏。它专职审核中书省提交的方案。审核不通过（封驳），则打回重做；审核通过（准奏），方案才能进入执行阶段。这相当于强制性的QA环节，从源头把控任务质量。
- 尚书省 (shangshu)：调度大脑。负责将门下省审核通过的任务方案，根据子任务类型，派发给对应的六部执行，并协调各部之间的依赖（如果有），最后汇总各部的执行结果，形成完整的“回奏”。
六部+吏部：专项执行单元。每个部门有自己擅长的领域：
- 户部 (hubu)：数据处理、报表、资源核算。
- 礼部 (libu)：文档撰写、规范制定、报告生成。
- 兵部 (bingbu)：代码开发、算法实现、工程构建。
- 刑部 (xingbu)：安全检查、合规审计、风险管控。
- 工部 (gongbu)：基础设施、CI/CD、部署运维。
- 吏部 (libu_hr)：Agent管理、权限维护、绩效记录（“功过簿”）。
早朝官 (zaochao)：情报与播报。定时聚合新闻资讯（“天下要闻”），并在每日首次打开看板时进行播报。

实操心得：角色人格（SOUL.md）是关键每个Agent目录下的SOUL.md文件定义了它的“灵魂”。这不仅仅是简单的系统提示词（System Prompt），而是包含了其职责描述、工作流程、输出规范、甚至沟通风格的详细定义。例如，门下省的SOUL.md会强调其“挑剔、严谨、注重风险防范”的性格，并明确规定审核时必须检查的几个维度（完整性、可行性、安全性）。在初始化项目时，install.sh脚本会将这些SOUL.md写入每个Agent的Workspace，这是系统能按设计运转的前提。千万不要随意修改这些文件的核心职责定义，否则会破坏整个权限体系的平衡。

2.2 权限矩阵与状态机：不可逾越的规则

光有角色不够，必须用规则限制它们能做什么、不能做什么。

权限矩阵定义了Agent之间的通信许可。这不是全联通网络，而是一个有向图。例如：

太子只能给中书省发消息（传旨）。
中书省可以给门下省（提交审核）、尚书省（同步方案）发消息。
尚书省可以给六部发消息（派发任务）。
六部只能给尚书省回消息（汇报结果）。
门下省无权直接命令六部。

这个矩阵写在openclaw.json的配置里，通过install.sh脚本自动设置Agent的sessions.visibility来实现。它确保了信息流严格按照“圣旨→太子→中书→门下→尚书→六部→回奏”的路径流转，防止越级指挥或信息混乱。

状态机则定义了单个任务的生命周期。一个任务从创建到完成，必须经历一系列合法状态，例如：Taizi（太子分拣）→Zhongshu（中书规划）→Menxia（门下审核）→Dispatched（已派发）→Doing（执行中）→Review（待审查）→Done（已完成）。

在kanban_update.py中，有一个_VALID_TRANSITIONS字典，严格定义了哪些状态可以转换到哪些状态。任何试图进行的非法状态跳转（比如试图把一个正在执行Doing的任务直接标记为Taizi）都会被系统拒绝并记录审计日志。这保证了流程的严肃性和可追溯性，避免了任务状态被随意篡改。

为什么这么设计？在实际的AI协作中，我遇到过太多“状态漂移”的问题。一个任务因为某个API调用超时，状态可能卡住，也可能被错误地标记为完成。有了严格的状态机，结合后文会提到的事件总线（EventBus）和审计日志，任何状态变更都是一个“事件”，可以被监听、记录和回放。当出现问题时，你可以清晰地看到“任务卡在了从Menxia到Dispatched的转换上”，而不是笼统的“任务失败了”。

2.3 前后端分离与一体化部署

Edict采用了一个务实且优雅的架构：React 18 + TypeScript构建的前端看板，与一个零外部依赖的Python标准库（http.server）后端。

前端（dashboard/）：使用Vite构建，Zustand进行状态管理，包含了看板、监控、配置等13个功能组件。它提供了丰富的交互界面来展示和控制系统。
后端（dashboard/server.py）：这是一个单文件约2300行的服务器。它同时做了两件事：
1. 作为API服务器，提供所有看板需要的RESTful接口（任务列表、状态更新、模型配置等）。
2. 作为静态文件服务器，直接托管前端构建好的dashboard.html及其资源。

部署上的巧思：在开发或Docker部署时，我们通常会构建前端（npm run build），然后将生成的dist目录交给后端服务。但在server.py中，作者采用了一种更直接的方式：它内嵌了构建好的HTML内容（或从文件读取），使得整个应用可以通过python3 server.py一键启动，无需关心Node.js环境。Docker镜像里则直接包含了预构建的前端资源。这种“一体化”部署方式极大地简化了运维复杂度，特别适合快速演示和个人使用。

注意事项：前端开发与生产构建如果你想修改前端UI，需要进入dashboard/目录，安装Node.js依赖（npm install），然后运行npm run dev进行开发。修改完成后，必须执行npm run build来生成新的静态文件，并确保server.py能正确指向这些新文件。对于大多数使用者来说，直接使用预构建的版本即可，无需接触前端代码。

3. 军机处看板：你的AI协作指挥中心

Edict的看板（Dashboard）名叫“军机处”，这绝非虚名。它是一个功能强大的实时监控与控制系统，是你作为“皇上”统御整个AI朝廷的界面。其设计原则是：全局可视、实时反馈、精细控制。

3.1 核心功能面板详解

看板由10个主要功能面板构成，信息密度高但布局清晰。

1. 旨意看板（Kanban）这是最核心的面板，采用看板视图展示所有任务。任务卡片在不同状态列（如“中书规划”、“门下审核”、“六部执行”）间拖动，直观反映流程进展。每个卡片上都有关键信息：旨意标题、负责部门、创建时间、以及最重要的——心跳徽章。绿色表示Agent活跃，黄色表示可能停滞，红色则表示告警（如长时间无响应）。你可以点击卡片查看完整的任务流转链，包括每个环节Agent的“思考过程”（Thinking）、工具调用和返回结果。在这里，你可以对任务进行“叫停”、“取消”或“恢复”操作。

2. 省部调度（Monitor）这是一个仪表盘视图。顶部以数字卡片形式展示各状态任务的数量（如“待审核：3”、“执行中：5”）。中间是横向条形图，直观展示任务在六部中的分布情况（例如，兵部任务最多）。下方是各个Agent的健康状态卡片，实时显示其最后活跃时间、当前负载等。一眼扫过，你就能掌握整个系统的运行负荷和健康度。

3. 奏折阁（Memorials）所有已完成的任务会自动归档到这里，形成一份份“奏折”。每份奏折以时间线方式清晰展示任务的五个阶段：圣旨原文、中书省规划方案、门下省审核意见、六部执行详情、最终回奏结果。支持一键复制为Markdown格式，方便你整理报告或分享。这是项目的“知识库”和审计追踪记录。

4. 旨库（Template Library）内置了9个预设的“圣旨模板”，覆盖常见场景：周报生成、代码审查、API设计、竞品分析、数据报告、博客文章、部署方案、邮件文案、站会摘要。选择模板后，会弹出表单让你填写具体参数（如周报的日期范围、涉及项目），系统会自动估算所需时间和Token消耗（费用），然后一键下旨。这极大地提升了常用任务的启动效率。

5. 官员总览（Officials）以排行榜形式展示所有Agent的“政绩”。包括Token消耗排行、任务完成数量、会话次数等。结合“功过簿”功能，这些数据可以用于优化Agent的模型分配（例如，将性价比高的模型分配给任务量大的Agent）。

6. 天下要闻（News）早朝官（zaochaoAgent）每日自动从预设的RSS源采集科技、财经等资讯，分类展示在看板上。你可以订阅感兴趣的类别，并配置飞书Webhook，将每日摘要推送到团队群。让AI系统也具备信息感知能力。

7. 模型配置（Models） & 8. 技能配置（Skills）这两个面板提供了运行时调整能力。在“模型配置”中，你可以为每个Agent单独切换底层的大语言模型（如从GPT-4换成Claude-3.5-Sonnet），更改后系统会自动重启Gateway（约5秒生效）。在“技能配置”中，可以查看每个Agent已安装的技能（Skills），并直接从GitHub等远程仓库添加新技能，无需修改代码。

9. 小任务（Sessions） & 10. 上朝仪式（Ceremony）“小任务”面板监控所有OpenClaw的实时会话。“上朝仪式”则在每日首次打开看板时，播放一个简短的动画，并展示今日统计，3.5秒后自动消失，增添了一丝趣味性和仪式感。

3.2 看板背后的数据流与同步机制

如此丰富的实时数据是如何实现的？核心在于一个轻量但高效的数据同步循环。

在scripts/目录下，有一个关键的脚本run_loop.sh，它启动了一个后台进程，每15秒执行一次数据刷新任务。这个循环主要做以下几件事：

从OpenClaw运行时同步：调用sync_from_openclaw_runtime.py，读取OpenClaw Gateway的实时数据，包括所有Agent的状态、活跃的会话（Sessions）、以及最重要的——每个会话中的消息流。这些消息流被解析、融合，转换成看板能理解的“任务”和“流转记录”。
同步Agent配置：调用sync_agent_config.py，确保看板中展示的Agent模型配置、技能列表与后端实际配置一致。
刷新官员统计：调用sync_officials_stats.py，计算并更新每个Agent的Token消耗、任务完成数等指标。
获取新闻：调用fetch_morning_news.py，更新“天下要闻”面板的内容。
应用模型变更：如果用户在看板上修改了某个Agent的模型，apply_model_changes.py会负责将配置写入对应的Agent Workspace，并触发Gateway重启。

这个15秒的轮询间隔是一个平衡点：既保证了数据的近实时性，又避免了对后端API的频繁请求造成压力。所有同步逻辑都封装在独立的Python脚本中，通过run_loop.sh串联起来，结构清晰，易于维护和扩展。

避坑技巧：数据不一致问题如果发现看板上显示的任务状态与实际不符，或者Agent心跳异常，首先检查这个数据刷新循环是否在正常运行。可以手动执行python3 scripts/refresh_live_data.py来触发一次强制刷新。另外，确保data/目录（运行时数据存储位置）有正确的写入权限，并且没有多个进程同时写入导致文件锁冲突（项目中使用file_lock.py来防止此类问题）。

4. 任务流转的完整实现：从下旨到回奏

理解了角色和看板，我们深入到最核心的业务逻辑：一个任务究竟是如何在12个Agent之间流转并最终完成的？这背后是一套结合了事件驱动、状态机和异步调度的复杂系统。

4.1 事件驱动架构与可靠投递

传统的Agent框架中，Agent间的通信往往是直接的、同步的函数调用或消息传递。这在分布式、可能出错的场景下很脆弱。Edict引入了事件总线（EventBus）模式进行解耦。

具体实现位于edict/backend/app/services/event_bus.py。它利用Redis的Streams数据结构作为消息队列。当一个Agent完成一项工作（例如，中书省生成了规划方案），它不会直接调用门下省的API，而是向一个特定的Stream（如edict:events）发布（publish）一个事件。这个事件包含了任务ID、事件类型（如zhongshu_plan_created）、以及相关的数据负载。

门下省作为一个独立的服务，订阅（subscribe）了这个Stream。它会持续监听新事件，当收到zhongshu_plan_created事件时，便触发自己的审核逻辑。

那么，如何保证事件不丢失？这里引入了事务性发件箱（Transactional Outbox）模式。代码实现在edict/backend/app/models/outbox.py和edict/backend/app/workers/outbox_relay.py。

其核心思想是：当业务逻辑（如中书省保存规划方案）需要发布事件时，并不直接发布到Redis，而是先将事件作为一条记录，与业务数据在同一个数据库事务中，插入到本地的outbox表。这个事务保证了“业务成功”和“事件记录保存”的原子性。随后，一个独立的outbox_relay后台进程，会定时扫描outbox表，将未发送的事件取出，真正发布到Redis EventBus，发布成功后再将记录标记为已发送。

这种模式确保了至少一次投递（At-Least-Once Delivery）。即使在中书省保存数据后、发布事件前程序崩溃，由于事件已保存在数据库，恢复后outbox_relay会重新发送。这是构建可靠分布式系统的关键模式。

4.2 状态机、调度器与工作流引擎

事件驱动解决了通信问题，而任务的生命周期和调度则由状态机和服务层控制。

状态机与审计：edict/backend/app/models/task.py中定义了任务模型和其状态字段。任何状态变更都不是简单的赋值，必须通过task_service.py中定义的服务方法（如transition_to_menxia_review）。这些方法内部会校验_VALID_TRANSITIONS，只有合法的状态转换才会被执行。每一次状态变更，都会通过audit.py记录一条审计日志，包含操作者、时间、从前状态、到后状态以及变更原因。这为问题排查和流程审计提供了完整依据。

并行调度引擎：dispatch_worker.py是尚书省背后的“劳动力”。当尚书省收到门下省“准奏”的事件后，它会解析任务方案，识别出可以并行执行的子任务（例如，“开发API”和“设计数据库”可以同时进行）。调度引擎会为每个子任务创建一个异步作业，提交到线程池或进程池中执行。它实现了指数退避重试机制：如果某个子任务因网络波动失败，不会立即放弃，而是等待一段时间（如1秒、2秒、4秒...）后重试，最多重试N次。同时，对于需要独占资源的任务，它还实现了简单的资源锁，防止冲突。

DAG编排器：对于有复杂依赖关系的任务（例如，必须先“创建数据库”才能“写入初始数据”），简单的并行调度就不够了。orchestrator_worker.py提供了一个基于有向无环图（DAG）的编排器。中书省在规划时，可以定义子任务之间的依赖关系。编排器会解析这些依赖，拓扑排序后，按正确的顺序调度任务执行。

实操心得：调试任务卡住在实际使用中，最常遇到的问题就是任务卡在某个状态不动了。我的排查步骤是：

看板优先：首先在“旨意看板”点击该任务，查看完整的流转链和每个环节的日志。往往能直接看到某个Agent报错（如LLM调用超时）。
检查事件：如果看板信息不全，去Redis里查看对应任务的Stream消息。使用命令XREAD COUNT 10 STREAMS edict:events 0-0，查看是否有相关事件产生。
检查Outbox：查看数据库中的outbox表，是否有事件卡在“待发送”状态。这可能是outbox_relay进程挂了。
检查调度器日志：查看dispatch_worker或orchestrator_worker的日志输出，看是否有异常堆栈。
Agent健康检查：使用看板的“省部调度”面板或API (/api/agents-status) 确认所有Agent是否都处于alive状态。

这套组合拳下来，绝大多数阻塞问题都能定位。

4.3 一个完整任务的生命周期实录

让我们以“审查一段FastAPI代码的安全性”这个旨意，走一遍完整流程，看看代码层面发生了什么。

下旨与分拣：你在飞书给中书省发送旨意。消息到达OpenClaw Gateway，被路由到taiziAgent。taizi的SOUL.md让它判断这不是闲聊，于是它执行kanban_update.py中的逻辑：

# 伪代码逻辑 if is_edict(message): # 判断是否为旨意 title = extract_title(message) # 提取标题，如“代码安全审查” clean_content = clean_edict_content(message) # 清洗内容，移除文件路径等元数据 task_id = create_kanban_card(title, clean_content, status="Taizi") audit_log(task_id, "Taizi", "旨意已接收并创建任务") send_message_to("zhongshu", f"新旨意[{task_id}]: {title}") # 触发事件

一个状态为Taizi的任务卡在看板创建，同时一个taizi_edict_created事件被发布。

规划与拆解：中书省zhongshu订阅了相关事件。它收到事件后，调用LLM分析旨意，将其拆解为子任务，例如：[“静态代码分析”， “依赖安全检查”， “JWT实现审查”]。它将这些规划写入自己的Workspace，并将任务状态更新为Zhongshu，然后发布zhongshu_plan_created事件。
审核与封驳：门下省menxia监听规划事件。它获取中书省的方案，调用LLM进行严格审查。审查可能不通过，此时它会将状态改回Zhongshu，并发布menxia_rejected事件，附上详细的驳回理由。中书省收到驳回事件后，会重新规划。这是一个强制性的反馈循环，直到方案通过。审核通过后，门下省将状态更新为Menxia，并发布menxia_approved事件。
派发与执行：尚书省shangshu监听准奏事件。它根据子任务类型（“安全审查”属于刑部，“代码分析”可能属于兵部），通过dispatch_worker并行派发任务。它会将任务状态更新为Dispatched，然后为每个子任务发布派发事件（如dispatch_to_xingbu）。
并行处理与汇总：刑部xingbu和兵部bingbu收到各自的派发事件，开始执行。它们会调用相应的技能（Skills），例如调用bandit进行Python静态分析，调用safety检查依赖漏洞。执行过程中，状态变为Doing。每个部门完成后，会向尚书省发送完成消息。尚书省收集所有部门的回奏，汇总成一份最终报告。
回奏与归档：尚书省发布shangshu_report_completed事件，并将任务状态最终更新为Done。看板的数据同步循环会捕获到这个最终状态，将整个任务的所有消息、流转记录打包，生成一份“奏折”，归档到“奏折阁”中。整个流程结束。

在整个过程中，kanban_update.py脚本和后台服务持续运行，监听这些事件，并实时更新看板数据库和界面，让你对一切了如指掌。

5. 扩展与生态：Skills管理与模型热切换

一个框架的活力在于其可扩展性。Edict通过“技能（Skills）”管理和“模型热切换”机制，让你能轻松地为其赋能和调优。

5.1 远程Skills生态：即插即用的能力

Skills是OpenClaw中赋予Agent特定能力的模块。Edict极大地简化了Skills的管理，支持从远程仓库（如GitHub）一键添加。

Skills文件规范：一个标准的Skill通常是一个SKILL.md文件，其中定义了技能的名称、描述、输入输出格式、以及具体的执行逻辑（可能是调用一个外部API或运行一段脚本）。官方维护了一个Skills Hub仓库（https://github.com/openclaw-ai/skills-hub），里面提供了诸如code_review（代码审查）、api_design（API设计）、security_audit（安全审计）等通用技能。

三种添加方式：

看板UI（最直观）：在“技能配置”面板，点击“添加远程Skill”，输入Agent ID、技能名称和GitHub Raw URL即可。

CLI命令（最灵活）：

# 添加单个技能到指定Agent python3 scripts/skill_manager.py add-remote \ --agent xingbu \ --name security_audit \ --source https://raw.githubusercontent.com/openclaw-ai/skills-hub/main/security_audit/SKILL.md # 批量从官方Hub导入技能到多个Agent python3 scripts/skill_manager.py import-official-hub --agents bingbu,xingbu,gongbu

skill_manager.py脚本会处理下载、解析、并将技能配置写入对应Agent的Workspace。

API调用（便于集成）：看板后端提供了RESTful API，方便与其他系统集成。

安全考量：从远程加载代码存在安全风险。Edict的skill_manager.py在下载后会进行简单的校验（如文件格式、关键字段），并建议用户只从可信源添加技能。对于生产环境，最好先将技能文件审核后，托管到内部仓库。

实操心得：创建自定义Skill如果你想为礼部(libu)添加一个自动生成API文档的Skill，可以：

参照官方模板，编写一个api_doc_generator.SKILL.md文件。
将其托管在GitHub（或内部Git）的某个仓库。
通过上述任一方式添加到libuAgent。
之后，当任务派发给礼部，且涉及文档生成时，它就可以自动调用这个新技能了。这大大扩展了每个“部门”的专业能力。

5.2 模型热切换与成本优化

不同的任务，对模型的要求不同。写诗可能需要GPT-4的创意，而数据提取可能用Claude-3-Haiku就够了。Edict支持为每个Agent单独配置和实时切换底层LLM。

在“模型配置”面板，你可以看到一个下拉列表，为每个Agent选择不同的模型提供商（OpenAI, Anthropic等）和模型型号。点击“应用”后，系统会：

将新的模型配置写入该Agent的Workspace配置文件。
向OpenClaw Gateway发送信号，重启对应的Agent进程（这个过程通常只需几秒）。
重启后，该Agent就会使用新的模型进行后续的推理。

为什么要这么做？—— 功过簿与智能路由agentrec_advisor.py（Agent推荐顾问）脚本维护着一份“功过簿”，它记录每个Agent使用不同模型执行任务的历史效果（成功率、质量评分）和成本（Token消耗）。结合linucb_router.py中实现的LinUCB（线性上置信界）算法，系统可以尝试进行智能路由。

其思想是：对于一个新任务，系统可以根据任务特征（如领域、复杂度）和“功过簿”中的历史数据，在探索（尝试新模型）和利用（使用已知好模型）之间取得平衡，为任务推荐一个预期效果最好或性价比最高的模型。虽然当前版本可能还未完全自动化此流程，但这套数据基础为未来的成本优化和性能调优提供了可能。

注意事项：模型兼容性切换模型时，需要注意不同模型的上下文长度、功能支持和输出格式可能略有差异。特别是如果Agent的SOUL.md中包含了针对特定模型（如GPT-4）的优化指令，换用其他模型时可能需要微调提示词。建议在非关键任务上先进行测试。

6. 生产部署与问题排查指南

将Edict用于个人项目和生产环境，关注点有所不同。下面分享从部署到运维的实战经验。

6.1 部署方案选型

Docker快速体验：这是上手最快的方式。项目提供了预构建的Demo镜像。
```
docker run --platform linux/amd64 -p 7891:7891 cft0808/sansheng-demo
```
这条命令会拉取一个包含了预配置Agent和模拟数据的完整环境。适合快速了解功能。注意--platform参数用于解决跨架构（如Apple Silicon的arm64机器运行amd64镜像）问题。
一键脚本部署（开发/测试）：如果你想基于自己的OpenClaw和API Key运行，这是推荐方式。
```
git clone https://github.com/cft0808/edict.git cd edict # 首先，确保已安装OpenClaw，并至少配置一个Agent（如taizi）的API Key # openclaw agents add taizi chmod +x install.sh && ./install.sh chmod +x start.sh && ./start.sh
```
install.sh脚本完成了所有繁重工作：创建Agent Workspace、写入SOUL.md、配置权限、同步API Key、构建前端（如果环境具备）。start.sh则同时启动了数据刷新循环和看板服务器。
Systemd生产部署：对于Linux服务器，需要长期稳定运行，建议配置为systemd服务。
```
sudo cp edict.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable edict # 开机自启 sudo systemctl start edict # 立即启动
```
项目提供的edict.service文件定义了服务如何运行。你也可以使用附带的edict.sh管理脚本进行启停。

部署决策建议：

个人学习/实验：直接用Docker Demo。
团队内部工具/轻度使用：使用一键脚本部署在一台内部服务器上。
关键业务流集成：使用Systemd部署，并考虑高可用方案（如使用Supervisor进程管理，配置日志轮转等）。

6.2 常见问题与排查手册

即使设计再完善，在实际运行中也会遇到问题。以下是几个最常见问题的排查思路。

问题一：任务卡住，Agent无响应

症状：看板上任务长时间停留在某个状态，负责该状态的Agent心跳变红。
排查：
1. 检查Gateway日志：tail -f /tmp/openclaw/openclaw-*.log，查看是否有网络错误、认证失败或模型超时。
2. 检查Agent进程：ps aux | grep openclaw，确认对应Agent的进程是否存在。有时进程可能僵死，需要重启。
3. 检查API Key与额度：确认使用的LLM API Key有效且有余额。这是最常见的问题之一。
4. 手动触发巡检：调用看板API手动扫描并重试卡住的任务：curl -X POST http://localhost:7891/api/scheduler-scan -H 'Content-Type: application/json' -d '{"thresholdSec": 300}'（扫描超过300秒无进展的任务）。

问题二：看板数据不同步或显示空白

症状：看板页面加载，但任务列表为空，或数据很久不更新。
排查：
1. 检查数据刷新循环：运行ps aux | grep run_loop，确认scripts/run_loop.sh脚本在运行。如果没有，手动启动它：bash scripts/run_loop.sh &。
2. 检查数据目录权限：确保运行Edict的用户对data/目录有读写权限。
3. 检查后端服务器日志：直接运行python3 dashboard/server.py，看启动是否有报错，以及访问API时是否有错误输出。
4. 检查浏览器控制台：按F12打开开发者工具，查看Network标签页中API请求是否失败（如404、500错误）。

问题三：添加远程Skill失败

症状：在看板或CLI中添加Skill时，提示下载失败或解析错误。
排查：
1. 网络连通性：尝试用curl或wget直接访问你提供的GitHub Raw URL，看是否能成功下载。国内网络访问GitHub可能不稳定，需要配置代理或使用镜像源。
2. URL格式：确保URL指向的是文件的原始内容（Raw），而不是GitHub的展示页面。正确的格式类似：https://raw.githubusercontent.com/user/repo/branch/path/to/SKILL.md。
3. 文件格式：下载下来的文件内容是否符合SKILL.md的规范？可以用skill_manager.py的验证功能检查：python3 scripts/skill_manager.py validate /path/to/downloaded.md。

问题四：Docker容器启动失败（exec format error）

症状：运行docker run时出现exec format error。
原因：你主机（如x86_64的Linux）的架构与Docker镜像的构建架构（如arm64）不匹配。
解决：强制指定平台运行：docker run --platform linux/amd64 -p 7891:7891 cft0808/sansheng-demo。或者使用docker-compose up，因为docker-compose.yml文件中通常已经指定了平台。

6.3 性能调优与监控建议

对于长期运行的生产环境，除了解决问题，还需要关注性能和状态。

资源监控：关注服务器的CPU、内存和磁盘使用情况。Edict本身不重，但运行的多个OpenClaw Agent进程和LLM API调用会消耗资源。可以使用htop或docker stats（如果容器化）进行监控。
日志管理：OpenClaw Gateway、Edict后端服务器以及数据刷新脚本都会产生日志。建议配置日志轮转（如使用logrotate），避免日志文件无限增大占满磁盘。
数据库维护：Edict使用SQLite（或你配置的其他数据库）存储任务和审计数据。定期清理已完成很久的旧任务数据，可以提升查询性能。可以考虑写一个定时任务（cron job）来归档或清理数据。
Token成本控制：充分利用“模型配置”功能，为不同职责的Agent分配合适的模型。例如，门下省审核需要较强的推理能力，可以用好一点的模型；而早朝官聚合新闻，用便宜的模型即可。定期查看“官员总览”中的Token消耗排行，分析优化空间。

从我自己的使用经验来看，Edict最大的价值在于它将AI协作从一个“魔法黑箱”变成了一个“可观测、可控制、可调试的工程系统”。这种基于明确规则和流程的设计，虽然初期学习成本比直接丢给CrewAI高一点，但在处理严肃、复杂、需要可靠结果的任务时，带来的可控性和安心感是无可替代的。它可能不是最快的框架，但很可能是最让你放心的那一个。