Skip to content

CommonTools / EdgeKnowledgeBase

Go to a project
Switch branch/tag
team-ai-workflow.md 6.07 KB

Team AI Workflow Guide

本文档用于向团队说明 VAServer 项目的 AI 辅助开发目录结构、权限边界和使用规范。

1. 总体原则

VAServer 项目采用“公共 AI 资料 + 各代码仓库私有 _ai 目录”的方式组织 AI 辅助开发资料。

核心原则：

  • 公共仓库只放跨团队可共享的信息。
  • 模块私有 AI 资料跟随代码仓库权限。
  • AI 默认是局部辅助工具，不改变原有人工开发、确认、提交流程。
  • AI 生成的代码、方案和文档必须经过人工确认。
  • 跨模块协作共享接口和行为，不共享内部实现。
  • AI 按 Superpower 模式使用团队共享 Skill：先加载项目上下文和规范，再执行任务。
  • 需求、设计、开发、测试四个过程都需要评审；重要任务必须留下评审结论。

2. 顶层目录结构

当前推荐结构：

VAServer/
  ai-public/        # 公共 AI 资料：架构、接口、规范、集成、共享知识、共享 Skills
  algorithm/        # 算法代码仓库
    _ai/            # 算法模块 AI 辅助资料，不参与编译
  cbox/             # CBox / Analysis Service 代码仓库
    _ai/            # CBox 模块 AI 辅助资料，不参与编译
  g6/               # g6 嵌入式代码仓库
    _ai/            # g6 模块 AI 辅助资料，不参与编译

3. ai-public 放什么

ai-public 是公共 AI 协作资料区，所有相关团队可读。

适合放：

  • 项目地图和仓库说明
  • 总体架构
  • 跨模块接口和协议
  • 共享需求
  • 集成任务
  • 通用编码规范
  • 通用 AI 编程规则
  • 团队共享 Codex Skills
  • 可共享领域知识

不应放：

  • 算法核心实现逻辑
  • 模型参数、训练数据、实验记录
  • 模块私有源码
  • 模块内部敏感设计
  • 只属于单个团队的调试记录
  • 未确认的 AI 代码草稿

4. 各项目 _ai 目录放什么

每个代码仓库下的 _ai/ 是本模块自己的 AI 辅助资料目录，权限跟随代码仓库。

统一结构：

_ai/
  00_requirements/       # 本模块需求
  01_prompts/            # 本模块常用 prompt
  02_design/             # 本模块内部设计
  03_task_runs/          # 重要 AI 任务记录
  04_code_drafts/        # 未确认代码草稿、patch、diff
  05_review_notes/       # 人工 review 和确认记录
  90_standards/          # 本模块补充规范
  93_knowledge_base/     # 本模块私有知识库
  README.md

说明：_ai/ 是辅助目录，不参与编译，不应被构建脚本当成源码目录处理。

5. AI 辅助开发分级

Level 1: 随手辅助

适合：解释代码、生成小函数、分析报错、补一段测试。

处理方式：可以不建正式任务记录，人工确认后使用。

Level 2: 模块内任务

适合：修复明确 bug、新增局部功能、重构一组文件、补充模块测试。

处理方式：记录到对应项目的 _ai/03_task_runs/。

建议一次任务一个目录：

_ai/03_task_runs/2026-06-07-task-name/
  input.md
  plan.md
  result.md
  changed-files.md
  test-result.md

Level 3: 跨模块任务

适合：算法与 CBox 接口变化、CBox 与 g6 协议变化、集成流程变化。

处理方式：

  • 公共部分放到 ai-public/40_integration_tasks/。
  • 接口文档放到 ai-public/20_interfaces/。
  • 模块内部细节放到各自代码仓库的 _ai/。

6. 代码修改和提交规则

默认规则：

  1. 人工提出需求或选择任务。
  2. AI 使用 $vaserver-development 或读取 ai-public/95_skills/vaserver-development/SKILL.md。
  3. 需求评审：确认目标、验收标准、模块范围、接口影响和风险等级。
  4. 设计评审：确认实现方案、兼容性、回退、异常处理、日志和测试策略。
  5. 开发评审：确认改动范围符合设计，不破坏接口、配置、数据格式和风险控制要求。
  6. 测试评审：确认已运行测试、未运行原因、人工验证项和剩余风险。
  7. 人工 review AI 的最终改动。
  8. 人工运行或确认必要测试。
  9. 人工确认后提交代码。

AI 默认不直接提交代码。提交权和最终责任在人工开发人员。

7. 权限边界

推荐权限：

目录 可见范围 说明
ai-public 所有相关团队 只放公共信息
algorithm / algorithm/_ai 算法组 算法代码和算法私有 AI 资料
cbox / cbox/_ai 软件组 CBox 代码和软件私有 AI 资料
g6 / g6/_ai 嵌入式组 g6 代码和嵌入式私有 AI 资料

跨团队沟通时，优先通过 ai-public/20_interfaces/ 和 ai-public/40_integration_tasks/ 协作。

8. 团队成员开始使用时先读哪些文件

公共入口：

  1. ai-public/00_project_map/project-overview.md
  2. ai-public/00_project_map/repo-map.md
  3. ai-public/00_project_map/module-boundaries.md
  4. ai-public/00_project_map/ai-entry-guide.md
  5. ai-public/00_project_map/team-ai-workflow.md

规范入口：

  1. 如果当前 AI 环境支持 Skill，优先使用 ai-public/95_skills/vaserver-development/ 对应的 $vaserver-development。
  2. ai-public/90_standards/ai-coding-rules-common.md
  3. 对应模块的补充规则：
    • 算法：ai-public/90_standards/ai-coding-rules-algorithm.md
    • CBox：ai-public/90_standards/ai-coding-rules-cbox.md
    • g6：ai-public/90_standards/ai-coding-rules-g6.md
  4. 各自项目 _ai/README.md

9. 命名建议

  • 公共 AI 资料目录：ai-public/
  • 团队共享 Skill 目录：ai-public/95_skills/skill-name/
  • 项目内部 AI 辅助目录：_ai/
  • 任务记录目录：YYYY-MM-DD-short-task-name
  • 文档优先使用 Markdown：.md

示例：

algorithm/_ai/03_task_runs/2026-06-07-optimize-preprocess/
cbox/_ai/03_task_runs/2026-06-07-fix-upload-timeout/
g6/_ai/03_task_runs/2026-06-07-sensor-reconnect/

10. 一句话版本

公共内容放 ai-public，共享 Skill 放 ai-public/95_skills，模块私有 AI 资料放各自代码仓库的 _ai/；AI 用 Skill 作为 Superpower，需求、设计、开发、测试逐步评审，代码最终由人工确认和提交。