2026Technology-Competition/docs/submission-spec-track1.md

# 参赛成果物提交规范 · 赛道一：Agent开发实战赛

> 适用范围：赛道一 · Agent开发实战赛全部参赛队伍（9 队）
> 说明：本规范为赛道一成果物提交的唯一标准。评审系统将依据本规范自动拉取代码、检测成果物并开展评审；不符合规范将导致成果物无法被采集或评审扣分。

---

**技术大赛现已进入中期发布阶段**。为配合中期检查 / 阶段性评审，现将赛道一《参赛成果物提交规范》发布如下。各参赛队须按本规范将成果物提交至 Gitea 仓库，评审系统将据此自动拉取、检测并评审。**不按本规范提交，成果物可能无法被采集，导致不得分或扣分。**

> ## ⚠️ 提交截止时间（重要）
>
> **中期成果提交截止：2026-08-31（周一）。**
>
> **若 8/31 前未能将成果物提交（push）到 Gitea 服务器，该队成果物将无法被评审系统采集，中期评审结果将直接受影响（视为未按时提交，按未提交处理，不得分）。**
>
> 请务必在截止时间前完成：账号登录 → 成果物放入仓库 → `git push` 到 main 分支，并确认服务器上能看到最新提交。

---

## 1. 中期成果提交

**赛道一各队均须提交中期成果**。中期评价**不要求全部成果物**，**将截至当前已完成的部分提交即可**——主要目的是让组委会了解各队**开发进度与项目状况**。

**提交时间**：**2026-08-31（周一）前**完成提交并 `git push` 到 main 分支；超过截止时间未提交 → 成果物无法被采集，中期评审按未提交处理（以仓库该时间点最新提交为准）。
> *注：以上为中期检查提交（8/31 前），建议尽量提交 §8 成果物清单中列出的全部成果物，以利最终评审的完整性判断。*

**提交方式与要求**：

- **提交对象**：赛道一全部参赛队伍
- **提交内容**：不要求全部提交——将已完成的部分提交即可（建议至少含：项目说明、设计文档、可运行源码、AI 使用日志；未完成的可注明"进行中"）
- **存放位置**：各队 Gitea 仓库 `2026Technology-Competition`，main 分支持续提交演进
- **账号凭据**：Gitea 用户名与密码由组委会另行联络下发；使用前先完成账号登录与密码核对
- **放置规则**：已完成成果物的命名与位置参照本文档 §8，与最终提交一致

## 2. Gitea 账号规范

| 项目 | 要求 |
|---|---|
| 用户名 | 使用组委会下发的**独立账号**（如 `T1-SD0102-01`），**禁止修改、禁止换绑** |
| 密码 | 使用组委会下发的初始密码，**请勿修改**。如修改评审系统将无法拉取仓库，会影响评审结果 |
| 账号用途 | 仅用于本大赛成果物存放，禁止外借、禁止在他处使用同一凭据 |

> 评审系统使用 `config/teams.json` 中的每队账号凭据自动拉取仓库，凭据被修改即拉取失败。

## 3. 仓库规范

> **仓库已由组委会统一创建**（命名、可见性、默认分支均已就绪），各参赛队**无需自行创建**，直接登录账号、按 §8 成果物清单放入文件并 `git push` 即可。

| 项目 | 要求 |
|---|---|
| 仓库位置 | 位于各队 Gitea 账号命名空间下（评审系统按 `https://gittea.dev/<账号>/<仓库>.git` 拉取） |
| **仓库名称** | **统一为 `2026Technology-Competition`**（连字符，无空格） |
| 可见性 | **Private（私有）**；评审系统使用每队下发的 token 拉取，无需公开 |
| 默认分支 | **`main`**；使用其他分支必须在报名表登记 |
| 仓库结构 | 成果物按 **§8 成果物清单与放置规则** 的结构存放；未按要求存放会影响评价结果 |
| 提交规范 | 截止前须 `git push` 到该私有仓库的 main 分支；评审以仓库最新提交为准 |

> ⚠️ 仓库名固定为 `2026Technology-Competition`，已统一构建完毕。若账号下未见到该仓库，请联系组委会确认账号与权限。

## 4. 项目性质声明（必填）

**评审区分新规/升级项目的考核要点，一经确认不可变更。**

| 项目 | 要求 |
|---|---|
| 声明位置 | 项目说明中明确标注 **`项目性质：新规` 或 `项目性质：升级`** |
| 新规项目 | 从零开发的新作品。提效/效果类维度须提供**对比数据**证明价值 |
| 升级项目 | 对存量系统/流程的改造。**强制要求**提交「存量系统分析」文档与「改造前后对比」数据（缺失则对应维度扣分） |
| 项目说明内容 | 项目概述、整体功能说明、效果总结（核心指标摘要）、团队分工、规模与技术难度自我评估 |

> 注：新规项目不需要提交「存量系统分析」与「改造前后对比」数据（系统为新开发），缺失不扣分；升级项目强制要求提交，缺失则对应维度扣分。

## 5. 开发范式与 AI 使用日志

**评审将范式图 ↔ AI 日志逐步骤对照验证开发过程真实性；AI 日志缺失或空白将扣分。**

### 5.1 开发范式流程图（必须提交）

- 范式图是**团队开发过程的工作流设计**（如：需求分析→AI生成方案→人工审核→AI编码→测试验证→反馈迭代），不是产品架构图。
- 放入**设计文档**（成果物02）。图中每个步骤的名称将对应出现在 AI 使用日志的"范式步骤"列。
- 评审时评委对照**范式图每个步骤 ↔ AI 日志对应记录**，验证范式是否真实执行。

### 5.2 AI 使用日志格式（`_AI_USAGE_LOG.md`）

根目录 `_AI_USAGE_LOG.md` 中每行/每表一条记录，**请包含以下字段**：

| 字段 | 说明 |
|---|---|
| **日期时间** | AI 修改代码的时间 |
| **范式步骤** | 与设计文档范式图中步骤名称**一致**（如"需求分析→AI生成方案"） |
| **修改摘要** | 本次 AI 修改做了什么 |
| **涉及文件** | 被 AI 创建或修改的代码文件路径（**评审抽检源码文件路径回查日志**） |
| **使用模型** | 本次使用的 AI 模型（如 DeepSeek、Qwen） |

**自动记录方法**：将以下规则写入项目的**指令文件**，AI 会在每次创建/修改代码文件后自动追加一条记录到 `_AI_USAGE_LOG.md`：

```markdown
## 日志规则（自动执行）
每次创建或修改代码文件后，在项目根目录的 `_AI_USAGE_LOG.md` 中追加一条记录，必须包含以下字段：日期时间、范式步骤、修改摘要、涉及文件、使用模型
```

各工具的指令文件位置：

| 工具 | 指令文件位置 |
|------|-------------|
| **OpenCode** | `opencode.md` 或 `AGENTS.md` |
| **Claude Code** | `CLAUDE.md` 或 `.claude/CLAUDE.md` |
| **Trae** | `.trae/rules/*.md`（建议 `alwaysApply: true`） |
| **Cursor** | `.cursor/rules/*.mdc`（建议 `alwaysApply: true`） |
| **GitHub Copilot** | `.github/copilot-instructions.md` |
| **Windsurf** | `.windsurfrules` |
| **Gemini CLI** | `GEMINI.md` |
| **其他工具** | 对应工具规则文件 |

> **注意**：评审系统能识别 `_AI_USAGE_LOG.md` 及 `ai_log` / `ai_usage` / `usage_log` 等变体文件名，但**建议统一使用 `_AI_USAGE_LOG.md`**（手册标准命名，最不易遗漏）。

## 6. 通用命名与内容红线

1. **文件名**：统一使用 ASCII 小写字母、数字、连字符（`-`）或下划线（`_`）。禁止空格、中文、全角字符、`&`/`#`/`%` 等特殊字符。
2. **禁止提交**：
   - 密钥 / token / 密码 / `.env` 等敏感文件
   - 构建产物：`node_modules/`、`dist/`、`build/`、`target/`、`__pycache__/`
   - 超大二进制文件（单个 >50MB）
3. **代码红线**：禁止硬编码绝对路径（如 `C:\...`、`/home/...`）、禁止硬编码 API Key/密码（须配置在环境变量或配置文件中）。
4. **README 必须为根目录文件**（嵌套 README 不满足要求）。
5. **信息安全**：顾客数据、公司内部数据不得上传至外部公开仓库，不得用于 AI 训练或上传至外部服务。
6. **编程语言不限**：任何能实现选题的技术栈均可。

## 7. 源码可运行前提（强制）

**源码无法按 README 启动运行的，后续所有评分项扣分**——这是基础前提项，不满足则整体扣分。

- 依赖须随仓库可复现（含依赖清单/锁文件），不依赖外部不可达资源。
- 若为 Web 类作品，请登记**服务地址（service_url）**，格式 `http://<域名或公网IP>:<端口>`。
- 服务地址用于评审期"系统验证（B 阶段）"：浏览器访问 + 黑盒冒烟，验证核心功能可达性。
- 服务无法访问（环境问题）不影响静态评分，但"声称的核心功能"将无法实测验证。

> **项目理解文档（评审必读）**：评审系统会读取仓库内文档与源码自动生成"项目理解文档"。因此代码与文档应真实反映实际实现，**文档声称的功能须能在代码/运行中找到对应实现**（存在"声称 vs 实测"交叉验证，不符将扣分）。

---

## 8. 成果物清单与放置规则

**构建步骤**：在已建好的 `2026Technology-Competition` 仓库 main 分支下，依次放入下列文件 → `git add .` → `git commit` → `git push origin main`。

成果物清单（按提交顺序）：

| # | 成果物 | 放置位置（命名） | 内容要求 |
|---|---|---|---|
| 01 | 项目说明 | 仓库根目录下的 `README.md` | 参赛作品的详细介绍，项目性质声明、项目概述、整体功能说明、效果总结、团队分工、规模与技术难度自我评估 |
| 02 | 设计文档 | 仓库根目录下的 `DESIGN.md`，或 `docs/`、`design/` 目录内 | 场景与价值、开发范式流程图、**Agent 架构图（感知-规划-行动-记忆）**、架构说明、工具/API 清单 |
| 03 | 源码 | 仓库根目录，或 `src/` 目录内 | **Agent + 交互界面 + 数据存储 + 工具调用**，可自主完成业务闭环；安装步骤、运行方法、环境要求、依赖清单写在 README.md |
| 04 | 实验报告 | `tests/` 目录内，附 `coverage/` 覆盖率报告与测试执行日志 | **Agent 闭环成功率、工具调用、异常恢复**数据 + 完整测试用例清单及执行结果。**评审系统以"测试真实运行且有用例"为准**（不会只因 tests/ 目录存在而判定已提交） |
| 05 | AI 使用日志 | 仓库根目录下的 `_AI_USAGE_LOG.md` | 覆盖需求/设计/编码/测试全环节，格式见 §5 |
| 06 | 演示视频 | `docs/` 目录下的 `demo.mp4`，或仓库根目录的 `demo.mp4`；也可在根目录 README 或 `docs/*.md` 中附视频链接 | ≤15 分钟：完整成功流程 + Agent 闭环 + 工具调用 + 异常恢复 |

**仓库目录结构（赛道一）**

```
2026Technology-Competition/            # 仓库根目录（main 分支）
├── README.md                          # 01 项目说明
├── DESIGN.md                          # 02 设计文档（含 Agent 架构图、范式图）
├── src/                               # 03 源码：Agent + 交互界面 + 数据存储 + 工具调用
│   └── …（项目源码）
├── tests/                             # 04 实验报告
│   ├── …（测试代码）
│   └── coverage/                      #    覆盖率报告
├── _AI_USAGE_LOG.md                   # 05 AI 使用日志
├── AGENTS.md                          # 评审必检：AI 协作方式与项目说明
├── data/                              # 评审必检：样本数据（也可用 sample/ 或 fixtures/）
└── docs/
    └── demo.mp4                       # 06 演示视频（≤15 分钟）
```

> 放置规则：
> - 成果物须位于仓库根目录或上表约定目录；评审系统不递归到任意深层目录。
> - 文件名/目录名用 ASCII 小写字母、数字、连字符、下划线，禁止空格与中文。
> - **评审系统另检测以下必填项**（缺失会降低"成果物齐全度"）：
>   - **AGENTS.md**（根目录）：AI 协作方式与项目说明，与 AI 使用日志配合溯源
>   - **样本数据**：`data/`、`sample/`、`fixtures/` 目录或随仓库提供的样例数据文件

## 9. 所需资源

| 资源 | 要求 |
|---|---|
| 开发环境 | 编程环境 + 终端（可运行 Agent 脚本、调用模型 API） |
| AI 模型/API | Agent 运行时调用的模型 API（DeepSeek/Qwen 等，见 §5.2；免费方案：OpenCode + DeepSeek） |
| 外部服务/账号 | Agent 用到的工具/API 账号（如有：数据库、第三方服务、代码平台 token） |
| 运行/演示环境 | 可运行 Agent 的服务或本地环境（Web 类建议登记 service_url） |
| 数据资源 | Agent 业务闭环所需样例数据、工具调用样例 |
| 测试资源 | Agent 闭环测试、工具调用成功率测试 |

> AI 模型 API 组委会不提供 token，由各队自备（推荐完全免费的 OpenCode + DeepSeek 组合）；海外服务使用注意信息安全（见 §6）。

## 10. 提交前自查清单

- [ ] **已在 2026-08-31 前提交并 `git push` 到 main 分支**
- [ ] 已用组委会账号登录 Gitea，密码未修改
- [ ] 已在项目说明中声明**项目性质（新规/升级）**
- [ ] 成果物齐全且按 §8 放置：README、DESIGN.md（含 Agent 架构图与范式图）、源码（Agent+界面+存储+工具调用）、tests/（测试真实运行）+ 覆盖率报告、`_AI_USAGE_LOG.md`、AGENTS.md、样本数据、演示视频
- [ ] `_AI_USAGE_LOG.md` 字段完整，范式步骤与范式图一致
- [ ] 文件名无空格/中文/特殊字符；无密钥/token/.env/构建产物
- [ ] 源码可按 README 启动运行；已 `git push`，本地与远端一致

## 11. 违规后果

- **超过 8/31 截止时间未提交 / 未 push 到服务器** → 成果物无法被采集，按未提交处理（不得分）。
- 仓库名、分支、凭据不符合本规范 → 评审系统**无法拉取**，按未提交处理（不得分）。
- 必填成果物缺失或命名不符 → 对应成果物判定为未提交，相关维度扣分。
- 文档/日志声称功能与实测不符 → 真实性考核扣分。
- AI 使用日志缺失或空白 → 相关维度扣分。
- 源码无法按 README 运行 → 后续所有评分项扣分。
- 升级项目未提交「存量系统分析」与「改造前后对比」数据 → 对应维度扣分。