AGENT-GUIDE.md — 面向 AI Agent 的使用指南

本文档专为 AI Agent 设计，提供快速上手所需的环境、配置、工具契约与最佳实践。

晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹版本：8.4.3 | 2026-09-14

一、项目简介

飞虹 Code（fhcode） 是一款运行在终端的 AI 编程智能体，支持：

自然语言 → 代码闭环：描述需求，自动规划、编写、验证
多模型路由：DeepSeek / 通义 / Ollama（本地）/ OpenAI 兼容
企业级安全：RBAC、审计链、多租户、配额熔断
全自动软件工程：swe 命令可自主完成仓库级开发任务

GitHub：github.com/wch887292/feihong-code（已上线）

二、环境要求

# 必需
Node.js >= 22.5.0（推荐 22 LTS 或 24）
npm >= 9

# 可选但推荐
git（--parallel 模式需要 worktree）
tsx（开发模式）

验证环境：

node --version  # 应 >= 22.5.0
npm --version   # 应 >= 9.0.0

三、快速安装

方式一：从源码构建（推荐）

git clone https://github.com/wch887292/feihong-code.git
cd feihong-code
npm install
npm run build

方式二：全局安装

npm install -g feihong-code
fhcode --version  # 验证安装

四、模型配置（关键）

4.1 环境变量优先级

FH_PROVIDERS（JSON 数组，最高优先级）
fhcode.config.json（项目配置文件）
单环境变量 FH_MODEL_*（快速接入）

4.2 Ollama 本地模型（推荐测试）

export FH_MODEL_NAME=qwen3:8b
export FH_MODEL_TYPE=ollama
export FH_MODEL_BASE_URL=http://localhost:11434
export FH_MODEL_TAGS=code-gen,reasoning,local

4.3 DeepSeek（推荐生产）

export FH_PROVIDERS='[{"name":"deepseek","type":"openai-compatible","baseUrl":"https://api.deepseek.com/v1","apiKey":"sk-...","tags":["code-gen","reasoning"],"priority":1}]'

4.4 离线 Mock（测试）

export FH_OFFLINE=true
# 或使用空 providers
export FH_PROVIDERS='[]'

4.5 沙箱三模式（P0-2，对齐 Codex）

export FH_SANDBOX_MODE=read-only            # 只读勘察（禁写禁执行）
export FH_SANDBOX_MODE=workspace-write      # 工作区可写（默认，shell 受白名单+审批）
export FH_SANDBOX_MODE=danger-full-access   # 全权限（危险命令黑名单仍生效）

# 网络域名规则（作用于 run_shell 命令中的 http(s) 目标）
export FH_NETWORK_DENY=evil.example.com     # 命中即拦截（任意模式生效）
# export FH_NETWORK_ALLOW=api.example.com    # 配置后未命中即拦截

4.6 MCP 外部工具（P0-3）

export FH_MCP_SERVERS='[{"name":"github","command":"npx","args":["-y","github-mcp-server"]}]'
# 远程工具以 <serverName>_<tool> 前缀注册（如 github_list_issues），沙箱/守卫同样生效

4.7 仓库级指令（P0-4）

在仓库根或任意目录放置 AGENTS.md（或 CLAUDE.md / .atomcode.md），任务启动时自动发现并注入 system prompt（限 8KB），无需任何配置。

4.8 hooks 确定性控制（P2-1）

# FH_HOOKS：JSON 数组。PreToolUse 非零退出会拦截工具调用；PostToolUse/PostEdit 只记录
export FH_HOOKS='[
  {"event":"PreToolUse","command":"node scripts/guard.js","tools":["run_shell"]},
  {"event":"PostEdit","command":"npx eslint --fix {path}","paths":["src/"]}
]'
# 占位符: {cwd} {tool} {path} {runId} {ok}

4.9 AGENTS.md 路径级规则（P2-3）

带 paths frontmatter 的规则只在操作相关文件时按需注入（JIT，省 token）：

---
paths: ["src/**", "tests/**"]
---
src 与 tests 目录规则：改动必须附带单元测试。

无 paths 的正文作为全局指令常驻注入。

4.10 插件分发（P3-3）

# 安装插件（本地目录或 git URL；清单 plugin.json 打包 skills + hooks + MCP）
fhcode plugin install ./my-plugin
fhcode plugin install git@github.com:user/my-plugin.git
fhcode plugin list                     # 列出已安装插件

插件目录结构：plugin.json（必含 name/version）+ 可选 skills/<name>/SKILL.md、hooks、mcp 配置。安装后自动生效（技能入索引、hooks/MCP 叠加）。

4.11 实时信息检索（P3-2）

内置 web_search（默认 DuckDuckGo，FH_SEARCH_ENDPOINT 可换端点）与 web_fetch 工具，目标域名受沙箱网络规则约束（FH_NETWORK_ALLOW/DENY）。

4.12 云执行任务队列（P4-1 / P6-4）

# 启动 Web 控制台（含 /api/tasks 任务队列，服务端静默执行）
fhcode serve --port 8080

# 提交任务（Bearer 鉴权）
curl -X POST http://localhost:8080/api/tasks \
  -H "Authorization: Bearer $FH_WEB_TOKEN" -H "Content-Type: application/json" \
  -d '{"goal":"写一个 hello.ts"}'
# 查询: GET /api/tasks 列表 · GET /api/tasks/:id 单任务

并发上限默认 2，可用 FH_TASK_CONCURRENCY 调整。 跨进程持久化（P6-4）：任务默认落盘 ~/.feihong-code/tasks/（可用 FH_TASK_PERSIST_DIR 覆盖），服务重启自动恢复队列——queued 重新入队执行、running 僵尸标记 failed（防崩溃遗留）。

4.13 Agent teams 多 agent 协作（P4-2）

# 目标自动拆解为任务清单，多 agent 并发认领执行，消息总线汇报
fhcode team "实现登录模块 并且 添加用户管理 并且 写集成测试"

内置消息总线（TeamBus）与共享任务清单（TaskBoard，原子认领防重复），逐任务结果摘要回传。

4.14 调度入口与消息渠道（P5-2 / P5-6）

# 任务状态 webhook（CI/外部系统编排）: FH_TASK_WEBHOOK_URL 或 POST /api/webhook {"url":"..."}
# 消息渠道推送（任务状态变化通知）
export FH_CHANNEL_TELEGRAM_BOT_TOKEN=bot:xxx
export FH_CHANNEL_TELEGRAM_CHAT_ID=12345
export FH_CHANNEL_WECOM_KEY=key1,key2        # 企业微信群机器人（可多个）

4.15 Docker 沙箱（P5-4）

export FH_SANDBOX_MODE=container             # shell 在容器内执行（docker run 挂载工作区）
export FH_SANDBOX_IMAGE=node:22-alpine        # 容器镜像（默认）

4.16 语义索引与 VSCode 扩展（P5-5 / P5-3）

符号索引：symbol-index.ts 自动提取函数/类/接口符号并缓存（FH_HOME/symbol-index.json），供 /grill 与 swe 聚焦
VSCode 扩展：vscode-extension/ 目录，fhcode.run / fhcode.diff 命令，配置 fhcode.binaryPath / fhcode.offline

4.17 Skills 市场（agentskills.io 对接）

# 搜索市场技能（默认 agentskills.io；--repo 或 FH_SKILL_MARKET 换源）
fhcode skill-market search "code review"

# 安装到 ~/.feihong-code/skills/（安装后任务中自动发现，渐进式披露）
fhcode skill-market install code-review

# 列出本地已安装技能
fhcode skill-market list

市场源协议：站点暴露 /.well-known/agent-skills/index.json（agentskills.io discovery 规范），支持 SKILL.md 直下与 tar.gz 归档（sha256 digest 校验防篡改，路径穿越防护）。

4.18 VSCode 扩展增强（P6-3）

# 在 vscode-extension/ 目录打包或 F5 调试加载
# fhcode: 运行任务（附带选区上下文）——选中代码自动作为 <selection> 上下文注入目标
# fhcode: 就地查看工作区 diff——VSCode 原生 diff 编辑器展示 HEAD ↔ 工作区
# fhcode: 查看最近任务输出

配置：fhcode.binaryPath（CLI 路径，默认 PATH 中的 fhcode）、fhcode.offline。 diff 面板通过 git show HEAD:<path> 提供左侧内容，需 git 仓库。

五、典型工作流

5.1 单任务执行

# 基础用法
fhcode "实现一个 HTTP 服务器，监听 3000 端口"

# 带约束
fhcode --max-iterations 10 --yes "修复 src/auth.ts 中的 token 验证 bug"

# 流式输出（P0-1：任务过程实时可见）
fhcode --stream "重构 src/calc.ts 的 add 函数"

5.2 并行子任务

# 自动拆分目标，worktree 隔离执行
fhcode --parallel "实现登录模块 并且 添加用户管理 并且 写集成测试"

M10 第一性原理拆解（默认开启）：--parallel 不再只按「并且 / 同时」等连词切分，而是从任务本质出发——识别每个片段所属的领域（实现/修复/重构/测试/文档/配置/接口/安全…）与目标文件域，拆成彼此独立的目标单元；无依赖的单元同一波次并行，文件域耦合的单元自动串行。启动时会打印当前拆解模式：

[飞虹 Code] 任务拆解: 第一性原理（领域本质 + DAG 分波次并行）

并发控制：并行子代理默认上限 3，可用环境变量调整（设为 1 即退化为串行）：

export FH_PARALLEL_CONCURRENCY=5   # 提高并发（额度充足时）
export FH_PARALLEL_CONCURRENCY=1   # 退化为串行（API 限流时）

关闭第一性原理（回退到旧连词规则拆分）：

export FH_FIRST_PRINCIPLES=0

5.3 全自动软件工程

# 读取整个仓库 → 规划 → 实现 → 验证 → 报告
fhcode swe "修复 src/calc.ts 的 add 函数 bug，让 tests/calc.test.ts 通过" \
  --repo /path/to/project \
  --max-tasks 3 \
  --max-iterations 5

M10 分波次并行（SWE）：swe 规划时先用第一性原理拆出多个独立实现单元（不同领域/不同文件域），并按依赖做拓扑分波次调度——同一波次内的子任务并行实现，波次之间串行等待前置完成（勘察 → 并行实现 → 测试 → 全量验证）。报告会显示调度波次数与每个任务所在波次（[wN]）。

SWE 并发上限（默认 2，防止同一仓库并行冲突与 API 限流）：

export FH_SWE_CONCURRENCY=3   # 提高 SWE 波内并行数
export FH_SWE_CONCURRENCY=1   # 退化为串行（保守模式）

FH_SWE_CONCURRENCY 同时作为 --parallel 的兜底并发值（FH_PARALLEL_CONCURRENCY 未设置时）。

5.4 只读技能

# 生成实现计划
fhcode /plan "实现登录并且添加支付"

# 红队审查（安全审计）
fhcode /grill src/

# 目标跟踪
fhcode /goal

5.5 技能标准（P1-2，SKILL.md）

内置 /plan /grill /goal 已迁入打包技能 skills/<name>/SKILL.md（open agent skills 兼容）：

模型侧：技能索引（name+description）常驻 system prompt，正文由 load_skill 工具按需加载（渐进式披露）
自定义技能：在仓库 .agents/skills/<name>/SKILL.md 或用户级 ~/.feihong-code/skills/<name>/SKILL.md 放一个带 frontmatter 的 SKILL.md 即自动发现

---
name: my-skill
description: 何时触发该技能
---
技能指令正文

5.6 跑分基准（P1-3）

npm run build && npm run eval        # 本地 mock 跑分（完成率/工具效率/自愈率）
npm run build && npm run eval -- --json   # 结构化输出（横向对比用）

5.7 子代理模型分工（P1-1）

swe / --parallel 的子任务自动带 ['code-gen','cheap'] 标签路由：低成本 provider（FH_PROVIDERS 中带 "cheap" 标签）优先承担子任务，主任务仍走 code-gen。未配置 cheap 标签时自动回退全部 provider，无感。

六、工具调用契约

6.1 工具清单

类别	工具	说明
文件	`write_file`	写入/覆盖文件
文件	`edit_file`	插入/删除/替换文本
文件	`read_file`	读取文件内容
文件	`list_files`	列出目录内容
搜索	`grep`	正则搜索
Shell	`run_shell`	执行命令
验证	`build_check`	检查编译
验证	`run_tests`	运行测试

6.2 工具参数格式

所有工具调用遵循 JSON Schema：

{
  "tool_calls": [
    {
      "type": "function",
      "function": {
        "name": "write_file",
        "arguments": "{\"path\":\"src/main.ts\",\"content\":\"export const x = 1;\"}"
      }
    }
  ]
}

6.3 工具返回格式

{
  "tool_call_id": "call_abc123",
  "output": "已写入 src/main.ts（25 字节）",
  "error": null
}

七、错误处理

7.1 常见错误码

错误码	含义	处理建议
`FH_4001`	配额超限	等待重置或申请配额
`FH_4003`	权限拒绝	检查 RBAC 策略
`FH_5001`	模型调用失败	检查 provider 配置
`FH_5002`	上下文压缩失败	使用 /plan 重新规划
`FH_6001`	文件路径越权	检查沙箱规则

7.2 调试技巧

# 查看详细日志
export FH_LOG_LEVEL=debug
fhcode "你的任务"

# 查看会话历史
fhcode sessions

# 恢复上次会话
fhcode resume <session-id>

八、企业部署

8.1 必需环境变量

export FH_ENTERPRISE=true
export FH_TENANT=my-org
export FH_USER=agent-sa
export FH_ROLE=developer
export FH_WEB_TOKEN=<web-console-token>

8.2 Web 控制台

# 启动服务
fhcode serve --port 8080

# 访问
# http://localhost:8080

九、验证套件

# 全量验证
npm run verify

# 单项验证
npm run verify:m4  # 企业能力
npm test           # 单元测试
node scripts/verify-m9.mjs  # SWE 能力

十、联系与反馈

GitHub Issues：提交 bug 或功能请求
文档：详见 docs/ 目录
署名：晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹

FilesExpand file tree

AGENT-GUIDE.md

Latest commit

History