使用说明

Betafits MCP工具

人工智能驱动的自动化工具，直接从Airtable管理的上下文中生成和审查存储库。该项目捆绑了共享的LangGraph编排、服务和实用程序，因此内部团队可以在不重写核心基础设施的情况下启动可靠的工作流程。

概述

Betafits MCP Tools是一个域存储库，它规范了我们如何：

生成遵循内部样式和Airtable模式的完整存储库。
审查现有的存储库，并根据Betafits评分标准对其进行评分。
通过LangGraph大脑路由传入请求，以便未来的节点（重构器、PCF工具等）共享相同的状态模型和工具。

该项目执行 Betafits工程标准：服务保存业务逻辑，工作流编排LLM调用，以及 lib/ 携带共享合约（LLM包装器、Airtable客户端、持久性帮助程序等）。

核心能力

代码生成器 (services/code_generator/run.py)
- 多步链提取需求，规划架构，构建存储库/文件夹/文件JSON，并可选择将其持久化回Airtable。
- 强制使用Airtable和Betafits编码风格的首选库。
代码审查员 (services/code_reviewer/run.py)
- 从Airtable中提取存储库、文件夹和文件，匹配传入消息，并分配评分标准。返回已准备好进行Airtable回写的结构化JSON。
MCP脑 (workflows/langgraph/orchestrator/nodes/brain_node.py)
- LLM路由器，用于选择哪个节点应处理用户消息。当前路由到生成器或审阅器，并已准备好使用其他节点（PCF解析器/写入器、重构等）。

建筑

message ──▶ LangGraph Orchestrator ──▶ mcp_brain ──┬─▶ code_generator_node ─▶ services/code_generator
                                                   └─▶ code_reviewer_node ─▶ services/code_reviewer

LangGraph: workflows/langgraph/orchestrator/graph.py 定义有向图。键入状态 lib/state.py.
服务：纯粹的商业逻辑。生成器和审阅者都暴露了 run() 可以从CLI脚本、测试或图形导入的函数。
气垫桌: lib/airtable_client.py 使用中定义的凭据获取存储库/文件夹/文件、字段映射、IO格式和库 .env.
LLM: lib/llm_client.py 包装OpenRouter（默认 openai/gpt-4o-mini)使用重试+限制。所有提示均已上线 services/<service>/prompt.py.
坚持: lib/code_generator_airtable_persistence.py 将生成的JSON转换为Airtable有效载荷，并批量创建存储库/文件夹/文件。

仓库布局

apps/                         # All entrypoints / CLIs
  workflow_cli/
    main.py                   # LangGraph workflow runner
docs/                         # Engineering standard, coding style, rubrics
  BETAFITS_CODE_GRADING_RUBRIC.md
  CODE_GENERATOR_AND_REVIEWER_DOCUMENTATION.md
  CODING_STYLE.md
  ENGINEERING_STANDARD.md
lib/                          # Shared clients, config, persistence helpers
services/
  code_generator/             # Multi-step generation chain + prompts + IO helpers
  code_reviewer/              # Review chain and entry point
  ...                         # (pcf_parser, pcf_writer, code_refactor scaffolds)
workflows/
  langgraph/
    orchestrator/             # Graph, nodes, and chaining logic
tests/
  README.md                   # Mirror lib/services/workflows when adding tests
requirements.txt
pyproject.toml

将代码保存在正确的文件夹（lib→ 服务→ 工作流）。看工程设计_ ANDARD.md 对于我们在CI中执行的导入规则。

先决条件

Python 3.12+
pip, venv，或 uv 用于依赖关系管理
Airtable库配备了以下引用的表
具有对已配置模型的访问权限的OpenRouter API密钥

设置

克隆
```
git clone <repo-url>
cd betafits
```

创建虚拟环境

# Preferred (uv):
uv venv .venv && source .venv/bin/activate && uv pip install -r requirements.txt

# Standard venv:
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

配置环境变量

复制 .env 或创建 .env.example 并设置：

OPENROUTER_API_KEY=<required>
OPENROUTER_MODEL=openai/gpt-4o-mini           # override as needed
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_SITE_URL=https://betafits.local
OPENROUTER_APP_NAME=Betafits MCP Tools
AIRTABLE_API_KEY=<required>
AIRTABLE_BASE_ID=<required>
TRANSFORMATION_PROJECTS_TABLE=<optional>      # Airtable table name for "Link to Transformation Projects"
DOCUMENTS_BASE_ID=<optional>                 # Airtable base ID for Documents/Resources
DOCUMENTS_TABLE_ID=<optional>                # Airtable table ID for Documents/Resources
PCF_BASE_ID=<optional>                        # Airtable base ID for PCF records (if different)
LG_RUNS_BASE_ID=<optional>                    # Airtable base ID for LG Runs + Snapshots
LG_RUNS_TABLE_ID=<optional>                   # Table ID for LG Runs
LG_SNAPSHOTS_TABLE_ID=<optional>              # Table ID for LG State Snapshots
LG_WORKFLOWS_TABLE_ID=<optional>              # Table ID for LG Workflows (name lookup)
LG_NODES_TABLE_ID=<optional>                  # Table ID for LG Nodes (name lookup)
LG_WORKFLOWS_NAME_FIELD=Name                  # Name field in LG Workflows
LG_NODES_NAME_FIELD=Name                      # Name field in LG Nodes
LG_WORKFLOWS_NODES_FIELD=LangGraph Nodes      # Linked field containing nodes on workflows
LG_LOGGING_MODE=auto                          # auto | full | minimal
LG_RUNS_MIN_FIELD_NAME=Name
LG_RUNS_MIN_FIELD_DESCRIPTION=Description
LG_RUNS_MIN_FIELD_STATUS=Status
LG_RUNS_MIN_FIELD_START_DATE=Start Date
LG_RUNS_MIN_FIELD_END_DATE=End Date
LG_SNAPSHOTS_MIN_FIELD_TITLE=Title
LG_SNAPSHOTS_MIN_FIELD_DETAIL=Detail
LG_SNAPSHOTS_MIN_FIELD_CREATED_DATE=Created Date
LG_SNAPSHOTS_MIN_FIELD_RUN_LINK=Related LG Runs Entries
LG_RUNS_FIELD_RUN_ID=Run ID
LG_RUNS_FIELD_WORKFLOW=Workflow
LG_RUNS_FIELD_TRIGGERED_BY=Triggered By
LG_RUNS_FIELD_TRIGGER_SOURCE_ID=Trigger Source ID
LG_RUNS_FIELD_STATUS=Status
LG_RUNS_FIELD_ENVIRONMENT=Environment
LG_RUNS_FIELD_INPUT_SUMMARY=Input Summary
LG_RUNS_FIELD_INPUT_PAYLOAD=Input Payload (raw JSON)
LG_RUNS_FIELD_OUTPUT_SUMMARY=Output Summary
LG_RUNS_FIELD_OUTPUT_PAYLOAD=Output Payload (raw JSON)
LG_RUNS_FIELD_STEP_LOG=Step Log (compact JSON array)
LG_RUNS_FIELD_ERROR_MESSAGE=Error Message
LG_RUNS_FIELD_ERROR_PAYLOAD=Error Payload (raw JSON)
LG_RUNS_FIELD_ENDED_AT=Ended At
LG_RUNS_FIELD_PCFS=PCFs
LG_SNAPSHOTS_FIELD_SNAPSHOT_ID=Snapshot ID
LG_SNAPSHOTS_FIELD_RUN=Run
LG_SNAPSHOTS_FIELD_NODE=Node
LG_SNAPSHOTS_FIELD_INDEX=Snapshot Index
LG_SNAPSHOTS_FIELD_TYPE=Snapshot Type
LG_SNAPSHOTS_FIELD_STATE_JSON=State Envelope JSON
LG_SNAPSHOTS_FIELD_SCHEMA_REF=Payload Schema Ref
LG_SNAPSHOTS_FIELD_SCHEMA_VERSION=Payload Version
LG_SNAPSHOTS_FIELD_STATE_HASH=State Hash
ENVIRONMENT=Local                             # Environment label for runs
WORKFLOW_SAVE_OUTPUT=1                        # toggle workflow output file writes

验证凭据

跑步 python - <<'PY' 测试 lib.config 如果密钥丢失，则提前升高：

python - <<'PY'
from lib import config
print("Config loaded successfully:", bool(config.AIRTABLE_API_KEY))
PY

运行LangGraph工作流

使用提供的线束 apps/workflow_cli 要端到端调用编排器：

python -m apps.workflow_cli.main "Generate a FastAPI service for employee onboarding"

要将本地文件作为生成器的附加上下文注入：

python -m apps.workflow_cli.main --context-file docs/LANGGRAPH_CONTEXT.md --context-file docs/CODING_STYLE.md "Generate a FastAPI service for employee onboarding"

支持的上下文文件类型： .md, .txt, .py, .json, .yaml, .yml, .docx, .pdf. DOCX/PDF提取需要 python-docx 和 pypdf （包含在 requirements.txt).

要将运行日志和状态快照持久化到LG Runs+LG state snapshots表中，请执行以下操作：

python -m apps.workflow_cli.main --log-runs "Generate a FastAPI service for employee onboarding"

如果 --workflow-name/--workflow-id 如果未提供，记录器会通过将运行的节点名称与 LangGraph Nodes LG工作流表中的链接。

它的作用：

构建初始 WorkflowState.
呼叫 workflows/langgraph/orchestrator/graph.workflow.
将存储库JSON保存到 <repo-name>.json 当 WORKFLOW_SAVE_OUTPUT 这是真实的。

提示：

集 WORKFLOW_SAVE_OUTPUT=0 在 .env 跳过编写工件。
检查 workflow_output.json 用于调试时的原始LangGraph状态。
使用 python -m apps.workflow_cli.main --help 样式调用，快速传递不同的提示。

增强现有存储库

代码生成器现在可以向现有的仓库添加功能，而无需构建全新的结构。提供回购名称（存储在Airtable中）和增强请求：

python -m apps.workflow_cli.main --repo-name ROI "Add a Slack notifier service"

这绕过了LangGraph并直接调用生成器服务。LLM只生成所需的其他文件夹/文件，在本地写入，并将其持久化回Airtable Folders/Files 桌子通过 lib/code_generator_airtable_persistence.

您还可以通过编程方式调用该服务：

from services.code_generator.run import run as generate_repo

generate_repo("Add Slack alerts", repo_name="ROI")

如果 repo_name 如果省略，则服务的行为与以前完全相同（net new repository generation）。

如果您有一个包含其他上下文的PCF记录，请将其传递给上下文引擎：

python -m apps.workflow_cli.main --repo-name ROI --pcf-record-id rec123 "Add Slack alerts"

generate_repo("Add Slack alerts", repo_name="ROI", pcf_record_id="rec123")

服务入口点

当您需要编写脚本或测试特定行为时，可以直接导入这两个服务。

from services.code_generator.run import run as generate_repo
from services.code_reviewer.run import run as review_repo

generate_result = generate_repo("Create a CRM integrations service", use_chain=True, persist=True)
review_result = review_repo("Review the onboarding automation repo")

use_chain=False 在生成器中，回退到单次提示(services/code_generator/prompt.py)并将文件保存在 generated_repository/.
集 persist=False 跳过将生成器输出推送到Airtable（在开发环境中很有用）。
审阅者目前总是只写JSON；气表持久性发生在链内，当 persist=True.

Airtable集成

工作流期望Airtable库公开以下表和视图：

表/视图	目的
`Repositories`, `Folders`, `Files`	生成或审查资产的标准数据存储。
`Field Mappings`	形状JSON键(`Current Name Field`)进入Airtable列。
`IO Formats`	声明代码生成器输出和代码审阅器输出的模式。
`Libraries`	标记首选库与非首选库。
`Documents/Resources`	工程标准和编码风格内容的可选来源。

在引入新字段或映射时更新这些表；服务调用中的辅助工具 lib/tool_registry.py 因此不需要额外的管道。如果Airtable数据缺失，代码会记录警告并恢复到默认值，但分级/执行将较弱。

如果 DOCUMENTS_BASE_ID/DOCUMENTS_TABLE_ID 配置后，上下文引擎将从文档/资源表中提取工程标准和编码样式（并包括链接到提供的PCF记录的任何文档）。未设置时，本地文档在 docs/ 而是使用。

开发指南

编码风格：关注 CODING_STYLE.md.快跑 ruff check . --fix 在每次提交之前，强制执行snakecase命名、导入顺序和格式。
测试：镜像下的仓库布局 tests/。为服务添加单元测试，为工作流添加集成测试。跑 pytest -q.
结构：将业务逻辑保持在内部 services/，编排 workflows/，并在中共享客户端/模型 lib/切勿将堆栈“向上”导入。
LLM提示：修改相关提示模板 services/<service>/prompt.py 文件并保持指令与Airtable模式+编码风格一致。
坚持：添加新Airtable字段时，更新 lib/code_generator_airtable_persistence.py 或者字段映射记录，以便持久性继续工作。

安全实践

输入验证：所有用户消息都通过 lib.validation.validate_user_message() 在调用服务以减轻快速注入尝试和超大负载之前。
秘密管理：秘密存在 .env （忽略了）。复制 .env.example，在本地填写凭据，永远不要提交原始密钥。 lib.config 当缺少所需密钥时，会很快失败。
审计：运行 ruff check . 和 pytest -q 在代码审查期间。安排对Airtable访问令牌的季度审查，并在任何人离开团队时轮换API密钥。

故障排除

缺少API密钥错误: lib.config 在以下情况下引发描述性异常 OPENROUTER_API_KEY, AIRTABLE_API_KEY，或 AIRTABLE_BASE_ID 未设置。仔细检查你的 .env.
路由到 END 立即：MCP大脑无法对信息进行分类。提供更多上下文或确保 OPENROUTER_MODEL 是有效的。
Airtable架构不匹配：更新字段映射记录，以便识别新列。持久性帮助程序记录它试图写入的列。
速率限制: lib.llm_client 自动退出，但如果超过OpenRouter配额，您可能仍会看到等待。减少批量大小或减慢呼叫速度。

参考文档

代码_生成器_审核者_文档.md –深入描述生成/审核链。
工程设计_ ANDARD.md –在Betafits中强制执行存储库形状和导入规则。
CODING_STYLE.md –衣冠、格式和文档要求。
BETAFITS_CODE_GRADING_RUBRIC.md –评论者链消耗的量规。
语言_文本.md –在生成器提示中注入可选的节点/边缘/链上下文。

每当您扩展提示、添加服务或引入新的贡献者时，请使用这些文档。

快乐建筑！

代码生成与审查工具

使用说明

Betafits MCP工具

目录

概述

核心能力

建筑

仓库布局

先决条件

设置

运行LangGraph工作流

增强现有存储库

服务入口点

Airtable集成

开发指南

安全实践

故障排除

参考文档

使用说明

Betafits MCP工具

目录

概述

核心能力

建筑

仓库布局

先决条件

设置

运行LangGraph工作流

增强现有存储库

服务入口点

Airtable集成

开发指南

安全实践

故障排除

参考文档

相关 MCP

JADX APK逆向分析MCP插件

Unity MCP AI游戏开发工具

代码库打包工具

Bitbucket Server 拉取请求管理 MCP 服务

AI校验服务

模型上下文协议服务器