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：

## 日志规则（自动执行）
每次创建或修改代码文件后，在项目根目录的 `_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 运行 → 后续所有评分项扣分。
• 升级项目未提交「存量系统分析」与「改造前后对比」数据 → 对应维度扣分。