fmode-code-agent

fmode-code-agent · 纯 JS 网页版 Bot 智能体开发规则仓

未来飞马 — 让 AI 进化提前发生，让 AI 落地快人一步

fmode-code-agent 是 FMODE 组织下的 智能体（Agent）开发规则仓库：为「纯 JS（浏览器 + Node 双兼容、 无任何打包器）实现的网页版 Bot 智能体」定义一套可被 AI（Claude Code / FmodeCode）直接执行的工程规则。

本仓 不是 框架，也 不是 运行时库。它是 规则 + 脚手架技能 的组合体：

交付物	路径	作用
规则总纲	CLAUDE.md	AI 进入本仓/引用本仓的第一入口，索引全部规则
分层规则	.claude/rules/	三层架构、MCP/Skill、LangGraph 无构建、实测、部署、坑位逐篇规范
全局技能	skills/fmode-code-agent/	给 AI 的智能体项目初始化技能 + 脚手架

姊妹仓：fmode-code-lit（Lit 前端无构建规范）。 前端细节以 lit 仓为准，智能体细节以本仓为准，两者可叠加使用。

一句话记住它

Agent 决策、MCP 协议、Skill 执行。换 Agent 框架时，MCP 与 Skill 一行不改。

三层架构

Agent（决策）   决定「这轮调不调工具、调哪个」。可换框架（PageAgent ⇄ LangGraph）。
  └─ MCP（协议） 把工具暴露成 JSON-RPC 2.0（浏览器常跑在 Web Worker）。不含业务编排。
       └─ Skill（实现）真正干活（出图/转写/分析），纯函数式能力。

验收标准：本项目把 Agent 从 PageAgent 换到 LangGraph，MCP 与 Skill 零改动。

规则索引

#	规则篇	内容
1	agent-architecture.md	三层职责、图编排 vs Re-act、State 放什么、可观测性
2	agent-mcp-skill.md	MCP 契约、多 MCP 命名空间、Worker 铁律、Skill 注册/调用、隔离
3	no-build-langgraph.md	LangGraph.js 浏览器无构建配方（importmap + 3 替身 + 6 坑）
4	llm-gateway.md	OpenAI 兼容、usage 真值、静默忽略参数陷阱、多模态拼接
5	measurement.md	token 归因、输入/输出比例、框架调度 vs IO 计时
6	agent-ui-bridge.md	事件流/阶段/进度、失败如实说明、移动端
7	deployment.md	无构建部署 + 自动部署（hook/CI/watch）+ 验真
8	pitfalls.md	24 条血泪坑位合集

技术底座

• 语言：纯 JS（ESM），浏览器与 Node 双兼容（核心无 Node 专有 API）
• 图编排：LangGraph.js（@langchain/langgraph），浏览器靠 importmap + 替身直跑
• 工具协议：MCP（JSON-RPC 2.0），浏览器端跑在 Web Worker
• 模型调用：自写最小 OpenAI 兼容客户端（不引 SDK）
• 观测：自写 telemetry（token / 耗时分离）
• 部署：无构建直传 OBS + CDN；提交后自动部署

用法

# 1) 生成智能体骨架
node skills/fmode-code-agent/scripts/scaffold.mjs ./my-agent --project my-agent

# 2) 给已有项目装规则
node skills/fmode-code-agent/scripts/install-rules.mjs .

# 3) 自检
node skills/fmode-code-agent/scripts/smoke.mjs

四条铁律

1. 浏览器 + Node 双兼容：核心纯 JS；fs/path 只在分发脚本里用。
2. 不用构建：不引打包器；依赖走 importmap（浏览器）或 npm（Node）。
3. 凭据不进 Worker / 日志 / 代码：要凭据的动作在主线程执行。
4. 参数以实测为准：网关会静默忽略参数 —— 必须验证副作用，不能只看 200。

开源协议

MPL-2.0（见 LICENSE）。商标「未来飞马」等不随协议授权。