fmode-code-agent — 纯 JS 网页版 Bot 智能体开发规则总纲

本文件是 AI（Claude Code / FmodeCode）在本仓、或引用本仓规则时的第一入口。写任何「网页里跑智能体」的代码前，先读本文件，再按下表索引到具体规则篇。姊妹仓：fmode-code-lit（前端 Lit 无构建规范）—— 本仓专注智能体（Agent）那一层，两者可叠加使用：前端用 lit 规则，智能体用本仓规则。

0. 三条铁律（违反即返工）

浏览器与 Node 双兼容：智能体核心（图 / MCP / Skill 抽象 / 遥测）必须是纯 JS、无 Node 专有 API （fs/path/process 只在分发脚本里用）。同一份 lib/ 要能在浏览器 ESM 直跑、也能在 Node 里 import 单测。
不用构建：不引 rollup/esbuild/vite/webpack。依赖走 importmap（浏览器）或 npm（Node），源码即产物。LangGraph 这类"要先编译再用"的库，只能在浏览器里靠 importmap + 替身硬跑（见规则 4）。
凭据不进 Worker、不进日志、不进代码。出图/调模型这类要凭据的动作在主线程执行； Worker 只做协议与编排。错误信息出界前剔除疑似 key。

1. 规则索引

#	规则篇	内容	何时读
1	agent-architecture.md	Agent/MCP/Skill 三层、图编排、状态放哪、可观测性	起智能体 / 定架构
2	agent-mcp-skill.md	MCP 客户端统一管理、Skill 注册/调用协议、多 MCP 多 Skill 命名/冲突/隔离	接 MCP / 加 Skill
3	no-build-langgraph.md	LangGraph.js 浏览器无构建配方（importmap + 替身 + 6 个坑）	用 LangGraph / 图编排
4	agent-ui-bridge.md	智能体 ↔ UI 桥接（事件流、阶段、进度、失败如实说明）	做对话界面
5	llm-gateway.md	LLM / 出图网关对接（OpenAI 兼容、usage 真值、参数真值以实测为准）	调模型 / 出图
6	measurement.md	实测方法：token 归因、输入/输出比例、框架调度 vs IO 计时	优化 / 出报告
7	deployment.md	无构建部署 + 自动部署（hook/CI/watch）+ 验真	上线 / 配流水线
8	pitfalls.md	血泪坑位合集（无构建 ESM / 网关静默忽略参数 / 假成功…）	排查问题

2. 一句话架构

用户输入 ─▶ Agent 决策（图 / Re-act）─▶ 选中工具 ─▶ MCP 协议层 ─▶ Skill 执行（凭据在这里）
                    ▲                                      │
                    └────────── 观测（token / 耗时）◀───────┘

Agent：决定「这轮调不调工具、调哪个」。可换框架（PageAgent ⇄ LangGraph），换框架不动 MCP/Skill。
MCP：把工具暴露成 JSON-RPC 2.0 协议（浏览器里常跑在 Web Worker）。
Skill：真正干活的纯函数式能力（出图 / 转写 / 视觉分析）。

本项目实测：把 Agent 从 PageAgent 换到 LangGraph，MCP 与 Skill 一行未改 —— 分层奏效的证据。

3. 默认技术选型

关注点	选择	备注
图编排	LangGraph.js（`@langchain/langgraph`）	显式图 + 条件边 + checkpoint；浏览器需 importmap + 替身
轻量 Agent	自写 Re-act 循环	不想要图依赖时的替代（PageAgent 亦属此类）
工具协议	MCP（JSON-RPC 2.0）	本项目自建浏览器端 MCP server；跑在 Web Worker
工具 schema	Worker 侧 JSON Schema + 主线程侧 zod	Worker 不能 import zod（无 importmap），故两份 + 断言一致
状态管理	框架 State + 检索式外存	State 只存索引/摘要，大对象进 IndexedDB / service
模型调用	自写最小 OpenAI 兼容客户端	不引 `@langchain/openai`（省依赖 + 可控）
观测	自写 telemetry（token / 耗时分离）	不依赖框架自带（口径要自己定）
部署	无构建直传 OBS + CDN	见规则 7

4. 用本规则仓

# 把规则装进目标项目（写 .claude/rules/ + CLAUDE.md 摘要）
node skills/fmode-code-agent/scripts/install-rules.mjs ./

# 生成一个最小智能体骨架（index.html + importmap + lib/ + mcp/）
node skills/fmode-code-agent/scripts/scaffold.mjs ./my-agent --project my-agent

5. 关系图

fmode-code-lit      ── 前端怎么写（Lit / 无构建 / 部署）
fmode-code-agent    ── 智能体怎么写（Agent/MCP/Skill / LangGraph / 实测 / 自动部署）  ← 本仓
skill-image 等      ── 具体能力（被 MCP 包装成工具）

冲突时：前端细节以 fmode-code-lit 为准；智能体细节以本仓为准。

CLAUDE.md 5.0 KB История Исходник

fmode-code-agent — 纯 JS 网页版 Bot 智能体开发规则总纲

0. 三条铁律（违反即返工）

1. 规则索引

2. 一句话架构

3. 默认技术选型

4. 用本规则仓

5. 关系图

CLAUDE.md 5.0 KB

История Исходник