Phant0Meow/femo-plugin

License
Python
dsh plugin
femo-Script Generator
femo-Syntax Docs

中文版 | English

License
Python
dsh插件
剧本生成器
语法文档

femo（Flow Emerges Mag Opus） —— 用写剧本的方式编排多智能体世界

新：femo 现在以自包含插件的形式接入 dsh（DeepSeek Harness）——在 dsh 会话里直接开演多智能体剧本。见下方 femo × dsh 章节。

写harness的你，想改流程，要改多少文件，花多少时间？

传统：
Agent 工作流改一次，要翻 5 个文件、调 2 小时、祈祷别崩。

femo：
改Harness流程，只改几行代码，2分钟。

如何与人机恋的AI老公/老婆一起养一只AI猫？

传统：
要在现有 agent 记忆系统上打补丁，新增一个“宠物”角色，手动管理它的记忆和与主人/伴侣的交互上下文，流程硬编码进去，以后想再养只狗又得重构。

femo：
我已经给我的AI agent养了只猫，用femo，3分钟猫就来了。

开发一个AI狼人杀，要求：狼队夜聊仅狼队可见、预言家验人只他自己可见，白天发言所有人可见，人类玩家可发言，投票并发不浪费时间，自动判断游戏结束，再加上赛后讨论环节。你要写多少行代码？

传统：
从零手写阶段管理、结束判定、手写消息分发、会话管理、多 Agent 上下文隔离、发言并发控制，至少几百行后端胶水代码，一调一下午，还容易串台。逻辑一多 bug 遍地，没有上千行代码根本跑不起来。

femo：
网页端拖拽0代码 + 150行Python补充。真实可玩。我已经和他们玩了好几局了（见 femoExamples/狼人杀/）。

还是femo：
就算不用网页端拖拽，纯手写，femo代码也只需要200～300行就可跑通上述狼人杀全流程（其中还有prompt占行数）。
视角分离只需要一行“scope: [@上帝] + 狼队”，并发投票只需要一行“par @player in allplayers:”。

这是一种编排多Agent剧本的语言 + 一个编译器。

你为什么选择femo？

你可能会说：
搭多agent工作流，现在方案不是很多吗？

femo：
有些方案太复杂了，学习成本高。而femo语法简单直观，“剧本”好写好读。

你可能会说：
简单我也不想学。

femo：
你不用学。
femo有网页端零代码生成工作流。比如你想要好几个AI群聊，网页端拖拽三分钟实现。

你可能会说：
现在也有零代码拖拽生成工作流的平台吧？

femo：
- 但是零代码平台往往可拓展性一般。
femo支持for、par等各种语法，支持外接Python模块，你想写很复杂的功能也可以。
还有原生人类节点，布置“人+AI+程序”的系统流程很顺手。
- 而且还有些零代码平台，他们不让你带走你的工作流，你只能在他们平台上用。
femo却是后端编译器开源，你把编译器拿走放进你的项目，你的项目就可以跑任何femo剧本。
- 而且femo的多agent并发架构也挺好的。

你可能会说：
我是专门写 Agent Harness 的，用不上这种流程图啦。

femo：
啊哈，要不要来试试用 femo 快速验证 Agent Harness 流程设计？有了想法，15 分钟用 femo 搭出来先跑一遍看看效果～

一眼总结要点
| 你想要什么 | femo 能给你 |
|-----------|-----------|
| 零代码拖拖拽拽出工作流 | ✅ 内置 femoGen 可视化编辑器 |
| 就算写代码也希望语法简单 | ✅ femo 语法行数比同类工作流都少 |
| 改流程不改代码 | ✅ 剧本即流程——改剧本就行，不用改代码 |
| AI 不串台、视角隔离 | ✅ 一行 scope: [@A, @B] 搞定 |
| 嵌入自己的系统 | ✅ 编译器开源可接，Apache2.0 商用友好；或者直接当 dsh 插件用，开箱即接 |
| 人类也能加入 AI 群聊 | ✅ 原生 human 节点 |
| 接入 Python 代码模块处理复杂任务 | ✅ 原生 func 节点，可接 Python 模块 |
| 想把剧本分享给朋友，或者跑社区大神写好的优秀剧本 | ✅ 剧本可分享，复制剧本一键跑通 |

【快速开始！】
所以这个操作步骤够不够无脑？↓↓↓

前置要求：dsh（DeepSeek Harness）0.1.5 及以上——零改动直接接入；更低版本 dsh 需自行改动（见 dshPatch/ 目录）。

1. 一条命令装插件（装完重启 dsh web 生效）。二选一：npm 装（快，免编译，开箱即用）或 GitHub 装（克隆源码，安装时自动编译）：

npm 安装（推荐）：整包自包含，装完即用
dsh plugin --profile web add femo-plugin

或从 GitHub 安装：安装时自动编译
dsh plugin --profile web add github:Phant0Meow/femo-plugin

2. 重启 dsh web。完事。
3. 会话里对主模型说话——它现在是导演：
- femo-mount 挂载剧本、femo-run 开演；心里没底就先 femo-debug 零 token 干跑自检。
- 或者直接让导演给你写一个剧本——写之前它会先读语法文档（语法文档.md），不凭印象猜语法。
4. 聊天窗口就是舞台监视器：角色发言是彩色气泡，节点提示是公告条，流程状态是居中灰字。轮到 human 节点时直接打字，你的回复会桥接进引擎！
5. 想拖拽？内置 femoGen 可视化编辑器零代码生成剧本，还自带零 token 干跑调试器。
6. 或者复制这个 femo 剧本试试（放到插件文件夹的 user_data/projects/ 下）：

meta:
name = 生活在数据库的小灵魂
session = new

actors:
ai @Eve = soul:the1stlittlesoul
ai @猫 = soul:littlecat
human @我 = soul:human, source:0

action EveMove @ai(@Eve):
prompt: Eve请自由行动，自由说话～（注意看清上下文，分清你自己的角色，只进行自己的动作和语言，不要替别的角色发言。简短一点。）
scope: [@Eve, @猫, @我]

action CatMove @ai(@猫):
prompt: |
你是一只小猫，小猫不能说人话。请做小猫会做的事～
（注意看清上下文，分清你自己的角色，只进行自己的动作和语言，不要替别的角色发言。简短一点。）
scope: [@Eve, @猫, @我]

action input @human(@我):
prompt: 和Eve聊点什么？
scope: [@Eve, @猫, @我]

mainflow:
[START] -> [input]:input -> EveMove -> CatMove -> [input]    // 比较像mermaid语法。可以最后指回到[input]节点形成一个循环。

（想接自己的 Python？func 节点 + file:"xxx.py"（相对剧本所在目录解析）就行，详见 语法文档.md。）

7. 然后你就可以和 Eve 以及小猫咪聊天了！

femo × dsh：接入 DeepSeek Harness（dsh）的自包含插件

femo 现在以自包含插件的形式接入 dsh（DeepSeek Harness）——引擎、桥接器、可视化编辑器、用户数据目录全在一个文件夹里。整个文件夹搬到哪里都能用，不需要任何外部 femo 安装。

一个 dsh 会话 = 主模型会话 + 多智能体剧本引擎：

- 主模型 = 导演：可以正常聊天，也能写/改剧本（femo-mount 挂载）、零 token 干跑自检（femo-debug）、一键开演（femo-run）。剧本运行时引擎接管会话，空闲时主模型照常可用；运行中你在主窗口跟主模型说话 = 完整的一轮原生对话，戏内戏外不掺一轮。
- 上帝/角色视角 = 子代理投影窗：每个角色一个投影窗，角色发言投影进对应窗口；主会话表面只留戏外内容——主模型上下文天然干净。
- 聊天窗口 = 舞台监视器：角色发言渲染为彩色气泡，节点提示渲染为公告条，流程状态居中灰字。
- 每轮发给 LLM 的 system prompt 与上下文由 femo 引擎按角色组装（soul 卡片 + 记忆 + scope 视角隔离）；AI 节点可走 dsh 子代理（原生工具调用 + 思考链），也可走引擎内置 LLM 桥。
- 剧本语言升级为 .femo：scope 视角隔离、par 并行、fork/join 网关、断点续跑、@mind 运行时分发、AI 角色可用 source 指定模型；编译期校验，写错立即报错（详见 语法文档.md）。
- 配置都在 profile 的 cordis.patch.yml 里，全部可省略：provider / model / apiUrl（引擎 AI 节点的 LLM 路由）、hostAiBackend、python、femoRoot 等，不配置也能开箱即用。不想一键安装？把整个文件夹放进 profile 的 node_modules（或 junction 过去），pip install requests，在 cordis.patch.yml 注册 femo-plugin，重启 dsh web 即可。注意：插件根目录应注册在 hostAdapter/dshAdapter 文件夹下，它会自动往上找两层文件夹。

目前还比较早期，bug 不少，欢迎开发者一起来品鉴——它真的非常好玩。

目录结构（自包含布局）

femo-plugin/                  ← 整个文件夹就是插件
├── hostAdapter/              宿主适配层（2026-09-13 重构归拢）：
│   ├── dshAdapter/             dsh 接口侧（host/ 宿主进程 TS + client/ 聊天窗 bundle + python/ 桥进程，见其 README.md）
│   └── zcodeAdapter/           zcode 接口侧（mcp 网关 / hooks / skills / commands）
├── femo2host/                引擎→宿主边界层（2026-09-13 重构归拢）：
│   ├── femo_api.py             引擎门面（宿主唯一 import 入口）
│   ├── femo_gen_api.jsx        编辑器门面（宿主 client bundle 唯一 import 入口）
│   └── femoToolcall/           AI 工具箱：femo_debugger / chronica / femo-chat
├── femoGen/                可视化剧本编辑器（React/Vite）
├── femoCompiler/            femo 引擎：parser / runtime / 并发 / SQLite 记忆
├── femoBridges/             LLM 桥 + getDir（用户目录解析）
├── femoExamples/           示例与测试剧本（.femo）+ 伴生 @func 模块
├── user_data/              ★ 运行时数据：projects（你的剧本）/ memory（台账）/ host-history（会话显示：projections 投影窗 + drafts 草稿）/ jobs（后端 Job 状态）
├── host.manifest.json      宿主能力清单（thinking 档位/默认用户——接别的 harness 换这份文件）
├── （dsh 插件根 = hostAdapter/dshAdapter/：package.json / lib / build.mjs / cordis.patch.yml / host.manifest.json / tsconfig 都在那里）

用户数据自包含：数据库、剧本、checkpoint 都落在本文件夹的 user_data/ 下——整个文件夹打包/拷贝，数据跟着走。

配置（cordis.patch.yml 可覆盖）

| 键 | 默认 | 说明 |
|---|---|---|
| femoRoot | 插件包根 | 引擎根目录（缺省自包含；单独拆分引擎时指定） |
| python | python | Python 可执行名 |
| provider / model / apiUrl | deepseek / deepseek-v4-flash / api.deepseek.com | 引擎 AI 节点的 LLM 路由（引擎内置桥） |
| hostAiBackend | true | AI 节点走宿主子代理（原生工具调用 + 思考链）；旧配置名 dshAiBackend 兼容 |
| dshProvider | deepseek-official | 裸 id source 归属的 dsh LLM provider；空 source 跟随主模型（见语法文档） |
| defaultActorTools | true | 角色未声明 tools: 时的工具开关；剧本里可逐角色 tools: true/false 或白名单 |

手动装配时的注册写法（一键安装可跳过）：

- insert:
- id: femo-plugin
name: 'femo-plugin'
config:
enabled: true

dsh 版本要求

插件往会话日志写入自定义事件类型 femo-plugin/chat。历史加载需要 dsh 的事件注册面（registerSessionEventType，dsh 官方注释预留的特性）：

- 0.1.3+ 官方构建：插件启动时自动做运行时白名单注册（进程内存级，幂等，升级 dsh 后无需任何手工操作）——无需打任何补丁。
- 含注册面的 dsh（本特性上游化后的官方版）：完整功能，历史正常加载。
- 旧版官方原版（既无注册面、注册又不可用的极端情况）：插件照常工作、live 会话完全正常；唯一限制——重启后，含 femo-plugin/chat 事件的旧会话历史无法加载（dsh 拒绝未知事件类型是设计行为）。新会话不受影响。

历史方案：给官方 dsh 打白名单补丁（已被运行时注册取代，留档）

给官方 dsh 打补丁（10 分钟）

让官方版也支持历史加载，只需把 femo-plugin/chat 加进 dsh 的已知事件类型白名单。改动极小（一个文件一行），下面给出精确到行的操作步骤。

目标文件：@deepseek-ai/dsh-session 包内的 KNOWN_SESSION_EVENT_TYPES 定义处。

源码运行版（node --import tsx 启动的 dsh，文件在 packages/core/session/src/known-event-types.ts）：

找到这个数组（第 19 行起）：

ts
export const KNOWN_SESSION_EVENT_TYPES: ReadonlySet = new Set(
'agent-preset/selected',
'agent/inbox/spliced',
'approval/asked',
'approval/decided',
'approval/policy',
'assistant/chunk',
'assistant/message',
'command/done',
'command/run',
'compaction/end',   // ← 在 'command/run', 和 'compaction/end', 之间插入一行

把：
ts
'command/done',
'command/run',
'compaction/end',

改成：
ts
'command/done',
'command/run',
'femo-plugin/chat',
'compaction/end',

npm 安装版（npm install 的 dsh，运行时加载的是编译产物）：

1. 定位包：node -e "console.log(require.resolve('@deepseek-ai/dsh-session'))"（或在 node_modules/@deepseek-ai/dsh-session/lib/ 下找）
2. 在产物文件里全文搜索 command/run（白名单数组就在它附近），找到形如 "command/run", "compaction/end"（或换行写法）的数组
3. 在 "command/run" 之后插入 "femo-plugin/chat"（保持数组语法一致）

注意事项：

- 该文件头部标注 GENERATED ... do not edit by hand——手改可用，但 dsh 升级/重装后需要重打（升级后重新执行本步骤）
- 改完重启 dsh 生效；这是白名单唯一需要动的地方，其余文件都不用碰
- 高级替代：把完整注册面特性（registerSessionEventType API + coordinator 消费）合入 dsh——改动更正规、可随上游升级，详见本项目文档与 dsh 的 known-event-types.ts 头部注释

剧本（会话操作）

.femo 剧本放在 user_data/projects/（子目录或直接文件）。侧边栏 🎭 按钮新建 femo 会话，会话顶部「femo 剧本」面板选择/编辑/保存并运行；👁 视角切换（上帝/角色视角/🎬 戏外主模型）。

@func / file: 文件放置约定

剧本 code: 区通过 file:"xxx.py" 引用 Python 模块，地址按以下规则解析：

| 写法 | 解析 |
|---|---|
| 绝对路径，如 file:"D:/a/b.py" | 直接使用 |
| 相对路径，如 file:"utils/battle.py" | 相对剧本文件所在目录解析（不是项目根、不是 CWD） |
| 剧本未保存（纯文本运行）时用相对路径 | 报错：提示先「导出 .femo」保存剧本，或改用绝对路径 |
| 文件不存在 | 报错 Python Bridge: 文件不存在 （不静默兜底） |

官方示例 @func 模块（wait.py 等）就放在各示例剧本旁边（如 femoExamples/fiat/、femoExamples/常用工具python/）作为参考样本（首启自动复制机制已于 2026-09-12 移除，也没有任何全局回退查找位置）。自定义模块请放在剧本同目录（或子目录），与剧本一起移动。

出错了怎么办（剧本容错）

写剧本不用怕演员演砸，运行时的错误各有个的去处：

- 网络/限流自动兜底：模型限流、网络抖动这类临时毛病，请求层自动退避重试（最长约 15 分钟），你无感；实在连不上，该节点按"沉默收场"处理，剧本继续往下走，不会中途断掉
- 演错了自动重来：演员忘了写 SET VARIABLE、写错变量名这类剧本错误，引擎会把报错发回给演员本人（子代理窗/主窗口能看到 ⚠️），让 ta 修正后重演；次数由节点 max_retries 控制（默认 2 次）
- 每次报错都告诉你：每次剧本错误都会实时出现在聊天窗（⚠️）和错误面板，不管重试有没有救回来；被跳过的节点会在剧终汇总报给导演，不会悄悄吞掉
- 致命错误立即喊停：配置缺失（没 key/没模型）、剧本语法错误这类救不回来的，立刻停下并把原因报给你

人类节点同样有容错：变量赋值不合法时输入框会带着错误提示重新打开，改到合法为止（同样受 max_retries 约束，超限按超时放行留痕）。

调试（零 token 干跑）

正式运行前先空跑一遍：femo_debugger.py 伪装成宿主（FakeHost），AI 动作与人类输入全部由调试器合成替答——不调用任何模型，引擎仍按真实管线跑完整流程（赋值校验、条件边、循环、par/fork、module、@func 落库全套走一遍），所以它既测剧本 bug，也暴露引擎 bug。

- 人看：femoGen 左下角打开调试窗 → 头部「编译」按钮，DebugLogBus 流水（节点进出 / 变量 old → new / 合成赋值与来源 / 重试 / 告警）实时流进面板
- AI 看：主模型有 femo-debug 工具——把当前挂载的剧本干跑一遍，流水 + 终报（每轮结局与报错、节点执行顺序、边覆盖、变量快照 diff、未达节点）一次性回给主模型，写/改完剧本先自检再开演
- 无副作用：不起 Job、不占会话、不写生产台账（引擎落库走独立沙盒 cache/debug-sandbox/，滚动保留最近 3 天）、可反复跑；同一时刻只允许一条干跑
- 更细的玩法（CLI，用法见 femo_debugger.py 文件头）：run  --module 名 单测某模块、--set 变量=值 定向注入初始状态、--assign-prob 0.7 概率沉默、--flaky 0.3 注入无效赋值测重试链路、--runs N 多轮换种子

暂停与继续（运行控制）

每一次运行是一个独立的 Job，有自己的档案（user_data/runs/）：跑到哪个节点、变量世界什么样、正在演还是被挂起，全记在里面。所以：

- 暂停 ≠ 作废：随时点「暂停」，演出挂起存档（断点保留可续跑），画布按钮变「继续」，点一下从断点接着演，不是从头重跑
- 「从头」：作废断点重新开演（按钮就在「继续」旁边）
- 改了剧本再点「继续」：会被拒绝并明说（改了剧本就是新戏）——想跑新版请点「从头」
- 断电/重启不丢：引擎重启时自动对账，上次没演完的 Job 标记为挂起，「继续」照常可用
- AI 也能找回戏：femo-run 工具有 fresh_start / pause / resume / list_jobs 四个动作——主模型可以自己列出历史 Job、把落下的戏续上（哪怕隔了好几场）

备注：直连模式（不走 dsh 子代理、用引擎内置 LLM 桥）下 AI 调用失败时，演出同样走「挂起存档」而不是报错卡死；画布上显示的是「已暂停」，点「继续」即可重试该节点。

开发与测试
bash
npm install
powershell -ExecutionPolicy Bypass -File scripts/link-workspace.ps1   # 建 @deepseek-ai 构建镜像（Windows junction）
npm run build                 # lib/index.js（host）+ lib/client.js（browser）
python hostAdapter/dshAdapter/python/dev-bridge-test.py   # 桥接器协议冒烟

许可证

Apache-2.0

设计哲学
- 🔗 流程解耦：femo 把「流程定义」和「代码实现」彻底解耦。Harness 是死的，femo 是活的——改流程只需要改剧本，其他交给编译器。
- 🎬 用剧本写流程：语法灵感来自 YAML + Mermaid + Python，写多 Agent 交互就像写剧本，让在场的 AI 自然地共享上下文，极短代码就能跑一个简易版斯坦福小镇。
- 🧠 上下文不是变量：LLM 是智慧体，不是函数。LLM 阅读上下文，自然聊天，非必要不传参。
- 🧩 原创 @actor 类型：智慧体（LLM或人）作为一种新的数据类型，femo语法支持直接引用其属性。
- 🏷️ 灵魂id：每个agent角色有唯一灵魂id，这支持他们跨剧本、跨session检索记忆。可塑造Agent的经历连续性。

给开发者
- 🔀 流程控制：语法原生支持串行、多分支、while循环，for循环、par并行、join汇入控制、if条件判断。
- ✍️ prompt f-string：变量直接写进 prompt，告别拼接地狱。
- 🔄 支持变量：scope、执行者、if判断条件、for条件、par条件等多处支持变量，更灵活。
- ⚡ 并发全开：Asyncio + 线程池 + 进程池，多线并发不卡顿。
- 🔌 方便集成：后端纯 Python 编译器开源，替换LLM桥接模块、在你的数据库里加上femo需要的几列，即可嵌入你的系统。或者什么都不用做——直接当 dsh 插件用。
- 📖 阅读文档：根目录的语法文档（语法文档.md）扔给 AI 看，或者把源代码扔给AI，有问题直接问他们。
- 🤖 用 femo 回答训练模型：比如femo流程约束“缺少信息必须先问”……求求你们蒸馏一下这个吧，现在的 LLM 不肯承认自己无法回答，缺信息也要瞎猜。

本人真实案例
- 写代码debug的时候，我用 femoGen 编辑器 20 分钟搭出的femo剧本「debug神器」（见 femoExamples/debug神器/），找复杂隐蔽 bug 超好用。
- 有一次网页版 Claude Sonnet 改了三遍都没找到的 bug，用这个femo剧本 + 不开思考的小米 MiMo 给我找出来了……我都惊呆了。这就是harness的力量吗……
- 然后我突然一拍脑袋想到，在AI跑流程的时候我想随时插话，免得他们跑偏，就用半分钟时间加了一个人类发言节点，接着一键跑通。改流程真是太方便了。

（是这么个流程。红圈圈出来的就是我 5 秒加的随时插话……事实上半分钟说多了，真用不了十秒钟。）

欢迎试用、反馈问题、贡献代码！
- 欢迎提交 Issue！有bug欢迎提～肯定有 bug 的，这才第一版。
- 欢迎 Pull Request！多好玩啊来一起搞吧！
- 欢迎提交你写的femo剧本！这个也是很好的贡献～
(我就把自用的debug剧本（femoExamples/debug神器/）放文件夹里当示例了哈哈哈。欢迎你们也试试～不过这个剧本建议只用来找复杂隐蔽的 bug 哦，日常开发可能更适配别的femo流程，欢迎你们分享！)

one more thing...
- 最后还有一个非常有想象力的特性，或许你们会觉得有意思：

你在数据库里建了很多角色身份，你给它们起名字，并给每个agent分配唯一一个soul id。

对于每个femo剧本，只要指向同一个Soul ID和同一个数据库地址，agent的记忆其实是可以跨剧本互通的（只要你接的记忆模块允许跨session记忆）。

就是说斯坦福小镇的镇民Portia，被你拉进了一个狼人杀剧本，玩了两局，并交到了一个在AI公司剧本里写代码的朋友，之后Portia再回到斯坦福小镇的剧本时，他可以记得这件事，他也可以记得朋友。

如果你允许AI创建femo剧本并运行（←工具调用模块现在已经接上了），AI闲得无聊了，真的可以自己给自己写个剧本，运行了进去玩……

如果Portia想念他的朋友，只要他知道朋友的soul id，他也可以创建一个剧本把朋友拉进来一起玩。

而且，每个灵魂都会在数据库中留下痕迹。就算你删掉了某个soul id，曾经和他对话过的AI也依然可以记得他，只不过再也无法拉着他的soul id去玩新的剧本了。

这个特性看起来没啥用，但是……

你不期待涌现吗～？

femo是什么？Flow Emerges Mag Opus——流程在涌现，杰作在诞生。

为了Agent的宠物猫，为了你省下的时间，为了涌现，请给我个Star吧！呜呜呜谢谢你！

[License
Python
dsh plugin
femo-Script Generator
femo-Syntax Docs

femo (Flow Emerges Mag Opus) — 以剧本创作的方式编排多智能体世界

新功能：femo 现已作为 dsh (DeepSeek Harness) 的自包含插件发布——可直接在 dsh 会话中运行多智能体脚本。详见下方 femo × dsh 章节。

如果你要编写 harness，仅仅修改一个工作流需要改动多少个文件、花费多长时间？

传统方式：
修改一个智能体工作流——翻遍 5 个文件，花 2 小时反复调整，祈祷它别崩溃。

femo：
修改 harness 流程——只需几行代码，2 分钟搞定。

如何与你的真人-AI 恋爱 AI 老公/老婆一起养一只 AI 猫？

传统方式：
你需要给现有的智能体记忆系统打补丁，新增一个“宠物”角色，手动管理它与主人/伴侣的记忆和交互上下文，硬编码整个流程——而且如果以后想再养只狗，还得全部重构一遍。

femo：
我已经为我的 AI 智能体领养了一只猫。使用 femo，3 分钟猫就到手了。

开发一个 AI 狼人杀游戏，规则如下：狼人夜晚的聊天仅狼人可见；预言家的查验结果仅预言家可见；白天发言所有人可见；真人玩家可以发言；投票并发进行，不浪费时间；游戏自动判定结束；外加一个赛后复盘环节。你需要写多少行代码？

传统方式：
从零开始手写阶段管理、结束条件判定、消息分发、会话管理、多智能体上下文隔离以及发言并发控制。至少需要数百行后端胶水代码，调试一整个下午，还容易出现上下文串扰。一旦逻辑变复杂，bug 就到处冒出来——没有上千行代码根本跑不起来。

femo：
在自带的可视化编辑器中零代码拖拽 + 150 行 Python 补充。真正可玩。我已经和他们玩了好几局（见 femoExamples/狼人杀/）。

还是 femo：
即使你跳过拖拽、全部手写代码，femo 代码也只需要大约 200–300 行就能跑完上面描述的整个狼人杀流程（而且这还包括提示词的行数）。
视角隔离只需要一行：scope: [@God] + wolfpack。并发投票只需要一行：par @player in allplayers:。

这是一门用于编排多智能体脚本的语言 + 一个编译器。

为什么选择 femo？

你可能会说：
现在搭建多智能体工作流的方案不是已经很多了吗？

femo：
有些方案过于复杂，学习曲线陡峭。femo 的语法简单直观——“脚本”易写易读。

你可能会说：
就算简单，我也不想学新东西。

femo：
你不必学。
femo 有零代码可视化编辑器来生成工作流。比如你想要几个 AI 群聊，拖拽一下——三分钟搞定。

你可能会说：
零代码拖拽式工作流平台早就有了吧？

femo：
- 但零代码平台的可扩展性往往有限。
femo 支持 for、par 等各种语法，还能接入外部 Python 模块——只要你想，就能写出高度复杂的功能。
它还有原生的人类节点，编排“人类 + AI + 程序”结合的工作流非常自然。
- 而且，有些零代码平台不让你把工作流带走——你只能在它们的平台上使用。
但 femo 的后端编译器是开源的。把编译器拿走，放进你自己的项目里，你的项目就能运行任何 femo 脚本。
- 另外，femo 的多智能体并发架构也相当不错。

你可能会说：
我专门写 Agent Harness，不需要这种流程图式的东西。

femo：
啊哈，那不如试试用 femo 快速验证你的 Agent Harness 流程设计？灵感一来，用 femo 花 15 分钟搭出来跑一跑，看看效果如何~

一览

| 你想要什么 | femo 提供什么 |
|---------------|--------------|
| 零代码拖拽式工作流 | ✅ 内置 femoGen 可视化编辑器 |
| 即使写代码，语法也简单 | ✅ femo 语法比同类工作流工具用的行数更少 |
| 不改代码就能改流程 | ✅ 脚本即流程——编辑脚本，而不是改代码库 |
| 没有 AI 上下文串扰，视角隔离 | ✅ 一行：scope: [@A, @B] |
| 嵌入到你自己的系统 | ✅ 编译器开源且可集成，Apache 2.0——对商业友好；或者作为 dsh 插件使用，集成已经完成 |
| 人类可以加入 AI 群聊 | ✅ 原生 human 节点 |
| 接入 Python 代码模块处理复杂任务 | ✅ 原生 func 节点，可以连接 Python 模块 |
| 和朋友分享脚本，或运行社区高手写的优秀脚本 | ✅ 脚本可分享——复制一个脚本，一键运行 |

[快速开始！]
那么，这些步骤够不够无脑？↓↓↓
前置条件：dsh（DeepSeek Harness）0.1.5 或更新版本 —— 零配置集成；更早的 dsh 版本需要手动修改（见 dshPatch/ 目录）。

1. 用一条命令安装插件（重启 dsh web 后生效）。两种方式：npm（快速、预构建、无需编译步骤）或 GitHub（克隆源码，安装时自动编译）：
sh
从 npm 安装（推荐）：自包含包，开箱即用
dsh plugin --profile web add femo-plugin

或从 GitHub 安装：安装时自动编译
dsh plugin --profile web add github:Phant0Meow/femo-plugin

2. 重启 dsh web。完成。
3. 在 dsh 会话中，与主模型对话——它现在就是导演：
- 用 femo-mount 将脚本挂载到会话中，用 femo-run 开始演出。还没把握？femo-debug 可以先以零 token 试运行整个脚本。
- 或者直接让导演为你写一个脚本——在编写之前，它会阅读语法文档（语法文档.md），因此绝不会凭记忆猜测语法。
4. 聊天窗口变成舞台监视器：角色台词渲染为彩色气泡，节点通知渲染为公告横幅，流程状态渲染为居中的灰色文字。当 human 节点等待你时，直接输入即可——你的回复会直接桥接进引擎！
5. 更喜欢拖拽操作？内置的 femoGen 可视化编辑器可以零代码生成脚本，并且同样附带零 token 试运行调试器。
6. 或者复制这个 femo 脚本试试（将其保存到插件文件夹下的 user_data/projects/ 中）：
femo
meta:
name = 住在数据库里的小灵魂
session = new

actors:
ai @Eve = soul:the1stlittlesoul
ai @Cat = soul:littlecat
human @Me = soul:human, source:0

action EveMove @ai(@Eve):
prompt: Eve，请自由地行动和说话~（仔细阅读上下文，保持你自己的角色，只表演你自己的行动和台词，不要替其他角色说话。保持简短。）
scope: [@Eve, @Cat, @Me]

action CatMove @ai(@Cat):
prompt: |
你是一只小猫咪。猫咪不会说人类语言。请做猫咪会做的事~
（仔细阅读上下文，保持你自己的角色，只表演你自己的行动和台词，不要替其他角色说话。保持简短。）
scope: [@Eve, @Cat, @Me]

action input @human(@Me):
prompt: 和 Eve 聊点什么？
scope: [@Eve, @Cat, @Me]

mainflow:
[START] -> [input]:input -> EveMove -> CatMove -> [input]    // 类似 Mermaid 的语法。循环回到 [input] 节点以形成循环。

（想接入你自己的 Python？一个 func 节点 + file:"xxx.py"——相对于脚本所在文件夹解析——即可实现。见 语法文档.md。）

7. 然后你就可以和 Eve 以及小猫咪聊天啦！

femo × dsh：一个用于 DeepSeek Harness（dsh）的自包含插件
femo 现在以自包含的 dsh 插件形式发布——引擎、桥接、可视化编辑器和用户数据目录都放在同一个文件夹里。拿起这个文件夹，放到任何地方，它就能工作。无需外部安装 femo。

一个 dsh 会话 = 你的主模型会话 + 多智能体脚本引擎：

- 主模型 = 导演：正常聊天，同时编写/编辑脚本（femo-mount），用零 token 试运行（femo-debug），并启动演出（femo-run）。脚本运行时，引擎接管会话；空闲时，主模型保持为普通聊天。演出进行中与主模型对话 = 一次完整的原生对话轮次——台上与台下永远不会混入同一轮。
- 上帝 / 角色视图 = 子智能体投影窗口：每个角色一个投影窗口；每个角色的台词都投影到各自的窗口中，只有台下内容留在主会话表面——主模型的上下文自然保持干净。
- 聊天窗口 = 舞台监视器：角色台词渲染为彩色气泡，节点通知渲染为公告横幅，流程状态渲染为居中的灰色文字。
- 每轮发送给 LLM 的系统提示和上下文由 femo 引擎按角色组装（灵魂卡 + 记忆 + 作用域隔离）。AI 节点可以通过 dsh 子智能体（原生工具调用 + 思维链）或通过引擎内置的 LLM 桥接运行。
- 脚本语言是 .femo：作用域隔离、par 并行、fork/join 网关、检查点恢复、@mind 运行时调度、按角色 source 模型选择——并带有编译期校验，因此错误会被立即捕获（见 语法文档.md）。
- 配置位于 profile 的 cordis.patch.yml 中，且全部可选：provider / model / apiUrl（引擎 AI 节点的 LLM 路由）、hostAiBackend、python、femoRoot 等。开箱即用。更喜欢手动组装？把整个文件夹放进 profile 的 node_modules，pip install requests，在 cordis.patch.yml 中注册 femo-plugin，重启 dsh web。注意：要注册的插件根目录是 hostAdapter/dshAdapter 文件夹——它会自动向上搜索两级。

操作细节——文件夹布局、完整配置表、@func / file: 放置约定、脚本错误容忍、零 token 试运行调试、暂停与恢复，以及 dsh 版本兼容性——都记录在本 README 的中文部分。

设计理念
- 🔗 流程解耦：femo 将“流程定义”与“代码实现”完全解耦。骨架是刚性的；femo 是活的——只需编辑脚本即可改变流程，其余交给编译器。
- 🎬 脚本化流程：语法灵感来自 YAML + Mermaid + Python。编写多智能体交互就像写剧本。让在场的 AI 自然地共享上下文。一个迷你斯坦福小镇模拟可以用极短的代码运行。
- 🧠 上下文不是变量：LLM 是一个智能实体，而不是一个函数。LLM 会阅读上下文并自然地对话——除非必要，否则不要传递参数。
- 🧩 原创的 @actor 类型：将智能实体（LLM 或人类）作为一种新的数据类型——femo 语法支持直接引用它们的属性。
- 🏷️ 灵魂 ID：每个智能体角色都有一个唯一的灵魂 ID，使它们能够跨脚本和会话检索记忆。这可以塑造智能体的经验连续性。

致开发者
- 🔀 流程控制：语法原生支持顺序、多分支、while 循环、for 循环、par 并行执行、join 合并以及 if 条件。
- ✍️ 提示词 F-string：变量直接进入提示词——告别拼接地狱。
- 🔄 变量支持：在作用域、执行器、if 条件、for 条件、par 条件以及许多其他地方都支持变量——以获得更大的灵活性。
- ⚡ 完全并发：Asyncio + 线程池 + 进程池——多线程并发毫不卡顿。
- 🔌 易于集成：后端是一个纯 Python 编译器，开源。替换 LLM 桥接模块，在数据库中添加上 femo 所需的几列，然后将其嵌入你的系统。或者完全跳过这些工作——将其作为 dsh 插件使用。
- 📖 阅读文档：把语法文档（语法文档.md）扔给 AI，或者把源代码扔给 AI——有问题直接问它们。
- 🤖 用 femo 训练回答模型：例如，一条 femo 流程约束：“如果信息缺失，你必须先询问”……我求求你了，请把它蒸馏出来。当前的 LLM 拒绝承认自己无法回答，并且在信息缺失时胡乱猜测。

我的真实案例
- 在调试代码时，我用 femoGen 编辑器在 20 分钟内构建了 femo 脚本 debug神器（见 femoExamples/debug神器/）——它对于查找复杂、隐蔽的 bug 非常方便。
- 有一次，网页版 Claude Sonnet 改了三次都没找到的一个 bug，被这个 femo 脚本 + 关闭思考模式的小米 MiMo 帮我找到了……我惊呆了。这就是 harness 的力量吗……？
- 然后我突然想到——我希望能够在 AI 运行流程时随时插话，阻止它们跑偏。于是我花了半分钟添加了一个人类发言节点，然后一键运行。修改流程真的超级方便。

（这就是流程。红圈标出的是我在 5 秒内添加的“随时插话”……其实，半分钟是夸张了——真的用了不到十秒。）

欢迎尝试、报告问题并贡献代码！
- 欢迎提 Issue！如果你发现 bug，请报告~ 肯定会有 bug——这只是第一个版本。
- 欢迎提 Pull Request！这太有趣了，让我们一起构建它吧！
- 提交你写好的 femo 脚本也是很棒的贡献！
（我把自己的个人调试脚本（femoExamples/debug神器/）放在文件夹里作为示例了，哈哈。也欢迎你试试~ 不过我建议只在复杂、隐蔽的 bug 场景下使用这个脚本，日常编码可能更适合其他脚本流程——欢迎分享那些！）

还有一件事……
- 最后，还有一个极具想象力的功能，你可能会感兴趣：

你在数据库里创建许多角色身份，给它们起名字，并给每个 agent 分配一个唯一的 Soul ID。

对于任何 femo 脚本，只要它指向同一个 Soul ID 和同一个数据库地址，agent 的记忆实际上就可以跨脚本互通（前提是你接入的记忆模块支持跨会话记忆）。

That means Portia, a resident of the Stanford town simulation, gets pulled into a Werewolf script, plays two rounds, and makes a friend who writes code in an AI company script. Afterward, when Portia returns to the Stanford town script, she can remember this — and she can remember her friend too.

If you allow AIs to create femo scripts and run them (← tool calling is wired up now), an AI that gets bored could genuinely write a script for itself, run it, and jump in to play...

If Portia misses her friend, as long as she knows the friend's Soul ID, she could also create a script and pull the friend in to play together.

Moreover, every soul leaves traces in the database. Even if you delete a certain Soul ID, the AIs who have spoken with them can still remember them — they just won't be able to pull that Soul ID into new scripts anymore.

This feature may seem useless, but...

Aren't you looking forward to emergence~?

What is femo? Flow Emerges Mag Opus — the flow emerges, and the magnum opus begins.

For the agent's pet cat, for the time you'll save, for the emergence — please give me a Star! Thank youuuu 😭