pingtai_agent/steering_agent/README.md

Steering Agent

项目约束管理Agent，提供持久的项目知识，保证一致的代码生成。

核心功能

只做一件事：对整个项目进行约束，让AI始终在预定规则下生成代码。

核心价值

价值	说明
持久的项目知识	自动提取并维护项目的技术栈、规范、模式等信息
一致的代码生成	确保 AI 生成的代码符合项目既有风格和规范
减少重复解释	一次定义规则，所有代码生成自动遵循

提供能力

工具	功能
extract_project_knowledge	从代码库提取项目知识
add_rule	添加用户定义规则
remove_rule	移除规则
list_rules	列出所有规则
get_context	获取完整项目上下文
check_compliance	检查代码合规性
generate_steering_doc	生成规范文档

快速开始

本地运行

cd steering_agent
pip install -r requirements.txt
python run_api_server.py

Docker 运行

docker build -t steering-agent:latest .
docker run -p 8000:8000 steering-agent:latest

使用示例

1. 提取项目知识

curl -X POST http://localhost:8000/api/v1/extract \
  -H "Content-Type: application/json" \
  -d '{"project_path": "/path/to/your/project"}'

2. 添加规则

curl -X POST http://localhost:8000/api/v1/rules \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "must",
    "rule_content": "所有 MCP 工具必须返回 JSON 格式",
    "category": "output"
  }'

3. 获取项目上下文

curl http://localhost:8000/api/v1/context?format=json

4. 检查代码合规性

curl -X POST http://localhost:8000/api/v1/check \
  -H "Content-Type: application/json" \
  -d '{
    "code": "def my_tool():\n    return \"result\"",
    "file_type": "python"
  }'

知识提取内容

类别	提取内容
技术栈	语言、框架、版本、依赖
目录结构	项目布局、关键文件、项目模式
命名规范	文件命名、类名、函数名、变量名
代码模式	异步使用、错误处理、日志方式、文档字符串
配置规范	环境变量、配置文件

规则类型

类型	说明	示例
must	必须遵循	"所有函数必须有 docstring"
must_not	禁止事项	"禁止硬编码 API Key"
prefer	推荐做法	"优先使用 async/await"
security	安全规则	"禁止使用 eval()"
architecture	架构规则	"MCP 工具必须定义在 mcp_server.py"

与其他 Agent 配合

与 specs_agent 配合

1. 使用 get_context 获取项目上下文
2. 将上下文传递给 specs_agent
3. specs_agent 生成符合项目规范的需求/设计文档

与 format_police_agent 配合

1. 使用 check_compliance 检查代码
2. 调用 format_police 检查输出格式
3. 确保所有输出符合规范

环境变量

变量	必需	说明
API_PORT	否	服务端口，默认 8000
API_HOST	否	服务主机，默认 0.0.0.0

项目结构

steering_agent/
├── Dockerfile
├── README.md
├── USAGE.md
├── requirements.txt
├── run_api_server.py
└── src/
    ├── __init__.py
    └── server/
        ├── __init__.py
        ├── api_server.py
        ├── mcp_server.py
        ├── extractors/
        │   ├── __init__.py
        │   ├── tech_stack.py
        │   ├── structure.py
        │   ├── naming.py
        │   ├── patterns.py
        │   └── config.py
        └── rules/
            ├── __init__.py
            ├── rule_store.py
            └── checker.py

服务端点

端点	方法	说明
/	GET	服务状态
/health	GET	健康检查
/mcp	POST	MCP JSON-RPC
/mcp/sse	GET/POST	MCP SSE 流式
/api/v1/extract	POST	提取项目知识
/api/v1/rules	GET	列出规则
/api/v1/rules	POST	添加规则
/api/v1/rules/{id}	DELETE	删除规则
/api/v1/context	GET	获取项目上下文
/api/v1/check	POST	检查代码合规性
/api/v1/doc	GET	生成规范文档

部署信息

配置项	值
镜像地址	agnettaiji.azurecr.io/ai-agents/steering-agent:latest
服务端口	8000
健康检查	/health