Domů Procházet Nápověda
Přihlásit se
fmode
/
fmode-code-agent
1
0
Rozštěpit 0
Soubory Úkoly 0 Pull Requesty 0 Wiki
Větev: main
Větve Značky
fmode-code-agen...
/
CLAUDE.md

CLAUDE.md 5.0 KB
Trvalý odkaz Historie Surový

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

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

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

  1. 浏览器与 Node 双兼容：智能体核心（图 / MCP / Skill 抽象 / 遥测）必须是纯 JS、无 Node 专有 API （fs/path/process 只在分发脚本里用）。同一份 lib/ 要能在浏览器 ESM 直跑、也能在 Node 里 import 单测。
  2. 不用构建：不引 rollup/esbuild/vite/webpack。依赖走 importmap（浏览器）或 npm（Node）， 源码即产物。LangGraph 这类"要先编译再用"的库，只能在浏览器里靠 importmap + 替身硬跑（见规则 4）。
  3. 凭据不进 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 为准；智能体细节以本仓为准。