参与贡献指南

语言 / Language: 中文 · English

感谢你对 AI Native ERP 的关注！这是一个面向生产级参考实现的开源项目，我们欢迎 Bug 修复、文档改进、测试补充和新功能提案。

开始之前

请先阅读：

README.md — 项目概览与快速开始（English）
ARCHITECTURE.md — 分层架构与数据流（English）
docs/zh/ai-governance.md — AI 治理约束
LICENSE — MIT 开源协议

你可以贡献什么

类型	示例
Bug 修复	意图误路由、检索结果不准、审批流异常
测试	域分类负样本、Tool 路由、知识检索分池
文档	README、架构说明、部署指南、截图
前端	页面体验、AI 侧边栏、可访问性
AI 能力	新 Tool、Intent Schema、RAG 质量、Guardrails
基础设施	Docker 一键启动、CI/CD、可观测性

开发环境

依赖

.NET 10 SDK
Node.js 18+
SQL Server（本地或 Docker）
DeepSeek API Key
Ollama（nomic-embed-text）
Qdrant（6333 / 6334）

启动

# 后端
cd src/AiNativeERP.WebApi
dotnet run --launch-profile http

# 前端
cd frontend
npm install
npm run dev

运行测试

# 后端全量
dotnet test src/AiNativeERP.Tests/AiNativeERP.Tests.csproj

# 前端
cd frontend && npm test

# E2E（可选）
cd frontend && npm run test:e2e

代码规范

通用原则

最小改动 — 只改与 Issue/PR 目标相关的代码
遵循现有风格 — 命名、分层、依赖注入方式与周边代码保持一致
可测试 — 核心逻辑应有单元测试，尤其是 AI 路由与业务边界
不写死密钥 — API Key、JWT Secret 等只放本地配置，不要提交到仓库

分层职责

Domain        → 实体与领域规则
Application   → 业务服务（唯一写库入口）
Infrastructure → EF、迁移、种子数据
AI            → LLM、意图识别、RAG、Guardrails
Agent         → 编排、Tool 路由、审批暂停
WebApi        → HTTP 入口、鉴权、DTO

禁止：

LLM / Agent 直接访问数据库
Tool 绕过 Application Service
实现 execute_sql、query_any_table 等万能 Tool
写操作跳过草稿确认直接落库

AI 相关改动 checklist

如果你修改意图识别、Tool、RAG 或 Agent 编排，请确认：

先识别 Domain，再识别 Intent
销售部员工 等人员问题归 HR，不归 Sales
制度/流程/手册 类问题归 Knowledge
多域歧义时返回 Clarify，不猜测
query_knowledge 只检索 knowledge_article，不与训练样本混池
写操作 Tool 标记 RequiresHumanApproval
新增负样本已写入 AiNativeERP.Tests

提交信息建议

使用简洁的英文或中文，说明 为什么 而不是只列文件：

fix(intent): route reimbursement policy queries to Knowledge domain

- boost KnowledgePolicyTerms in DomainClassifier
- add regression tests for 报销制度在哪里看

Pull Request 流程

Fork 仓库并基于 main 创建分支
分支命名：feat/xxx、fix/xxx、docs/xxx、test/xxx
确保 dotnet test 通过（如涉及前端则跑 npm test）
填写 PR 模板，说明改动动机与验证方式
等待 Review；有冲突时 rebase 到最新 main

PR 会被拒绝的情况

包含密钥、Token、个人路径
大范围无关重构
破坏 AI 治理约束（见上文）
缺少测试的核心路由/审批逻辑改动
未说明验证步骤

报告 Bug

请使用 Bug Report 模板，并尽量提供：

复现步骤
期望行为 vs 实际行为
用户输入原文（中文问法）
后端日志片段（如有）

功能建议

请使用 Feature Request 模板，说明：

业务场景
期望的用户体验
是否涉及写操作 / 审批 / 权限

社区行为

尊重他人，就事论事
欢迎新手提问，但请先搜索已有 Issue
维护者有权关闭不符合项目方向的 PR

再次感谢你的贡献。每一个 Issue、测试用例和文档改进，都会让这个 AI-Native ERP 参考实现更可靠。

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History