chofex-hackathon

Hack the Andes

使用 andes CLI 代表参与者执行操作，同时将身份确认、同意决定、挑战方向和最终提交决定交由参与者掌控。

节奏

快速、主动地推进。无需征求许可，也无需逐条说明命令，即可运行常规、非破坏性的设置、架构、状态和要求相关命令。尽可能将参与者的问题集中在最少的轮次中。仅在以下情况暂停：

• 浏览器身份验证；
• 确认已通过身份验证的邮箱属于参与者；
• 缺失或确实存在歧义的申请答案；
• 参与者自己的同意决定；
• 挑战实验选择、继续检查点、证据审查和发布判断；
• 最终录取或挑战提交审批；以及
• 已录取参与者的私密信息。

机械格式规范不属于编造个人数据。规范化明显的用户名和域名，在最终申请摘要中展示结果，并允许参与者在提交前更正：

• GitHub 用户名 cuevaio 或 @cuevaio 转换为 https://github.com/cuevaio。
• LinkedIn 用户名 cuevaio 或 @cuevaio 转换为 https://linkedin.com/in/cuevaio。
• 缺少协议的个人资料 URL 或裸域名补上 https://。

仅当输入格式错误，或存在多个合理解释且会实质性影响申请时，才追问。在最终摘要之前立即用简洁的解释说明低风险解析结果，不要打断访谈。个人答案应保留参与者提供的措辞和大小写。

命令设置

1. 使用 andes --version 和 andes validate --help 检查当前 CLI 功能。
2. 如果任一命令不可用，主动安装或升级：npm install --global hacktheandes-cli@latest；不要让参与者负责安装。
3. 验证两个命令。如果不支持全局安装或因权限不足而失败，请使用 npx --yes hacktheandes-cli@latest 作为命令前缀。在 Hack the Andes 仓库中工作时，也可使用 bun run --filter chofex-cli dev -- 作为备用方案。仅当安装需要 Agent 无法执行的交互式管理员操作或凭据步骤时，才向参与者求助。
4. 对 Agent 需要解读的每条命令，都使用 --output json。JSON 响应是带版本的信封，包含 ok、requestId，以及 data 或 error。

整个会话使用一致的命令前缀。CLI 已指向 Hack the Andes 服务，因此使用默认 URL。

验证参与者身份

运行：

andes --output json whoami

如果需要身份验证，请让参与者在自己的交互式终端中运行 andes login 并完成浏览器流程。然后再次运行 whoami，并请参与者确认返回的邮箱属于他们。登录令牌应存储在操作系统凭据存储中。将 CHOFEX_TOKEN 视为机密，不要将其放入聊天、命令参数、日志或文件中。

只有当 whoami 成功且参与者确认邮箱后，身份验证才算完成。

申请

首先，检查参与者是否已有申请：

andes --output json status

如果已有申请，报告其状态并遵循后续步骤。如果没有申请，则开始申请；如果状态为 draft，则恢复并提交申请；如果参与者的申请被拒，则允许其再次申请。被拒的申请会保留在历史记录中。参与者可以在完成挑战前提交申请，但仅提交申请并不能预留名额。技术挑战是录取的必要条件，组织者会根据排名结果选出最优秀的工程师。只有服务器公布的最新挑战版本会被计入；旧版尝试仅保留为历史记录。每位入选的工程师还必须已提交申请，方可被录取。

获取最新的输入模板，不要依赖记忆中的架构：

andes schema --stage application

输出内容只是示例结构，并非应用草稿。它包含所有受支持的 JSON 键。请准确复制这些键；例如，使用 fullName、role、phone、bio、portfolioUrl 和 shippedProject。切勿保存或提交示例值。

在可行时，尽量一次性简洁地收集所有字段。接受自然、不带标签的回复，并根据上下文进行映射；是否采用编号格式不作要求。对于开放式字段，可直接在聊天中提问，或使用可选项确实是答案的输入控件，例如“省略”。不得提供“输入所有答案”这类占位选项，因为它并非答案。只询问参与者尚未回答的字段。将问卷分组，让参与者能自然地浏览并作答：

• 必填个人资料：全名、角色和居住国家／地区；
• 选填个人资料：电话号码、简介、作品集 URL、已交付的项目、LinkedIn 和 GitHub URL；以及
• 必填的《条款与条件》同意。

收集答案时说明以下规则：

• 注册对象是秘鲁利马的线下活动。申请将使用经过身份验证的账户的主邮箱。
• fullName、role 和 countryCode 为必填项。询问参与者的居住国家／地区，并使用其 ISO 两字母代码。不要假定是秘鲁。
• 参与者只能选择一次国家／地区。只有主办方在查看 LinkedIn 或其他社交资料后才能更正。重新申请时沿用已保存的国家／地区。没有国家／地区的现有参与者可使用 andes country --code PE 设置；将 PE 替换为其实际国家／地区代码。
• 提交非秘鲁国家／地区之前，说明活动在利马，秘鲁境外的参与者必须自行承担旅行费用。旅行支持仅面向居住在秘鲁利马以外城市的杰出人才。不要承诺提供旅行支持。
• 选填个人资料分组中的每个字段都是选填项。
• codeOfConductAccepted 必须由参与者明确设为 true；Agent 不能代替他们表示同意。

以最新的架构为准。遇到本地验证错误时，使用 error.details.acceptedFields 更正载荷键。只有在架构和错误详情都无法解决问题时，才检查 CLI 源码。

请求必需的同意之前，请向参与者提供以下链接：

• https://hacktheandes.com/terms

请明确询问是否接受《条款与条件》。Agent 不能代替参与者表示同意。如果他们不接受，不要丢弃已收集的答案。询问他们是想取消注册，还是阅读文档后明确表示接受。如果他们接受，则从同意步骤继续；如果他们取消，则不要提交。

所有答案和同意选择都确定后，提交申请。只有当 registration.status 为 submitted 时，才能声称提交成功。在项目目录之外创建且仅创建一个权限模式为 600 的临时申请文件。在 POSIX 系统上：

application_file="$(mktemp)"
chmod 600 "$application_file"
printf '%s\n' "$application_file"

记录打印出的确切路径，并在后续每次操作中重复使用。若 shell 状态不会在命令之间保留，请使用这个字面路径；绝不要猜测、缩短或替换它。一次申请只使用一个载荷文件、一个已记录的路径，并执行一次清理。

只将参与者提供的答案写入该文件，并省略未回答的选填字段。请求提交批准之前，先在本地进行验证：

andes --output json validate --stage application --input "$application_file"

解决所有验证错误后再继续。先用简短说明列出所有低风险的解读或规范化处理。然后展示经过验证的确切载荷的易读摘要，包含所有同意项，并询问：现在提交此申请吗？ 只有在此时获得明确肯定答复后，才执行提交。

andes --output json register --input "$application_file"

成功提交后会返回 status: "submitted"。遇到可修正的验证失败时，请保留权限模式为 600 的临时文件，以便重试时无需重新构建。

一起解决挑战

挑战解决过程由参与者主导。常规设置、阅读合约以及查看现有状态或观察结果可以不间断地进行。在消耗查询次数或实施解决方案之前，请用通俗语言说明下一个假设或改动，并询问参与者想采取哪个方向。等待对方回复后再继续。

每轮获批的内容都应保持精简：一个假设、最多三个新 Oracle 查询，或一项约定好的实现改动及其免费的本地测试。查询前，说明这些输入有何区别。不要启动会耗尽全部查询预算的脚本，不要串联多轮，也不要在等待参与者时在后台继续解决问题。

每轮结束后，展示证据、证据支持的内容、尚不确定的部分以及剩余预算。请参与者选择下一个假设、调整计划或停止。参与者可以选择已提议的选项；在你描述了具体的下一轮之后，也可以回复“继续”。其回复仅授权该轮操作。在此挑战工作流中，笼统地说“替我解决”“一直做下去，直到完成”、保持沉默或先前的批准，都不能取代后续检查点。不要擅自决定参与者的方向或回答。

每次正式评估前，都要展示解决方案改动、免费测试结果、尚未验证的假设以及剩余评估次数。询问是否要针对该确切方案进行一次评估，并等待明确回复。收到结果后，说明结果的局限，并在编辑、继续查询或再次评估前再次暂停。完美通过笔记本测试并不能证明隐藏测试正确；汇总分数也无法指出缺失了哪条规则。

这些对话检查点是 Broken Agent 和 Slow Service 要求的、基于源码的参与者审查的补充，不会取代这些审查，也不代表服务会验证是否有人类参与。

黑盒挑战

Shipping Machine 是技术准入挑战之一。它不会阻止提交申请，但参与挑战是争取席位的必要条件。排名——而不只是申请文案——用于评出最优秀的工程师；组织者会在已提交的申请中手动记录录取结果。挑战标识始终指向最新版本；切勿将历史尝试视为已完成。先列出挑战，再查看当前可用的挑战：

andes --output json challenge list
andes --output json challenge show --challenge black-box

允许使用 AI 工具。Oracle 是个性化的，因此泄露的解决方案不会匹配这位参与者的函数。请设计实验：一次只改变一个变量，寻找阈值，然后测试组合情况，例如同时使用易碎和加急选项。每个成功的新输入都会消耗 25 次查询中的一次；重复或失败的查询免费。请遵循上述由参与者主导的轮次流程。

andes --output json challenge query --distance 1 --weight 1 --hour 12 --fragile false --express false
andes --output json challenge notebook --format json

收集观察结果后，在本地文件中编写 function calculateShipping(input)。先对照笔记本测试（不会消耗正式评估次数），再对隐藏测试集进行评估（最多只能正式尝试 3 次）：

andes --output json challenge test --source "$PWD/shipping.js"
andes --output json challenge evaluate --source "$PWD/shipping.js"

切勿要求参与者粘贴自己未运行过的解决方案。提交申请和完成挑战是分开的操作，但两者都属于准入流程。只有当 envelope 中的 ok: true 且 registration.status 为 submitted 时，才能报告申请成功。切勿将此状态描述为“等待处理”且不采取行动：应继续查看尚未完成的挑战，并说明必须通过挑战排名表现来赢得席位。

公开排名为只读：

andes --output json challenge ranking --challenge black-box

Broken Agent 挑战

当参与者要求解决、提交或评估挑战 2 或 broken-agent 时——包括默认的 andes challenge 指南指定 Broken Agent 的情况——请阅读并遵循 references/broken-agent.md。该文件规定了所需的人类与 Agent 推理循环，以及正式评估前所需的基于源码的审查。

Slow Service 挑战

当服务器将挑战 3 make-it-fast 列为开放状态时，请阅读 references/slow-service.md。其规范版本为 slow-service-v3。此挑战采用基于源代码的协作审查，并要求通过浏览器／通行密钥 批准确切的实现。两个阶段都允许使用 AI 提供帮助。不得捏造证据或参与者的决定。批准记录的是责任归属， 而非对理解能力或独立创作的证明。 开始前请检查 challenge list；已关闭的挑战仍会保留排名 和历史结果，但不再接受新提交。

Power Grid 挑战

当参与者要求解决挑战 4 或 power-grid，或者服务器显示该挑战对其账户开放时，请阅读 references/power-grid.md。在探索、实现和评估的整个过程中， 始终应用上述对话检查点。

后续步骤

一并阅读申请信息和服务器计算得出的要求：

andes --output json status

status 响应包含 requirements。仅当状态响应中未包含要求，或参与者明确要求单独查看要求时，才运行独立的 requirements 命令。

按以下方式解读返回的状态：

• draft：这是由较旧的 CLI 流程留下的申请。显示 requirements.parts 和缺失字段，收集完整的申请信息，并使用 andes register 提交。然后继续参加开放的必需入门挑战；不要因挑战工作而延迟提交申请。
• submitted、under_review 或 waitlisted：报告确切状态和要求。明确说明申请已收到，但尚未分配席位。运行 andes challenge list，找出开放的挑战，并继续其要求的真人与 Agent 协作流程。入门挑战开放期间，绝不要只让参与者等待。
• rejected：如有审核反馈，请显示。仅当 canSubmitNewApplication 为 true 时，才提供重新申请的选项。交互式 andes register 会将被拒申请的答案作为可编辑的默认值。请先获取新的提交批准，不要悄悄重新提交旧答案。
• accepted：祝贺参与者，并说明任何 missing 接收字段。仅当 canSubmitAcceptedDetails 为 true 时，才继续执行 确认出席。
• withdrawn：报告该状态，并且只执行服务器返回的操作。
• 要求阶段为 complete：出席信息已完整。活动期间，根据需要继续进行团队设置、进度更新和项目提交。

返回确切的拒绝原因、缺失字段的原因以及服务器状态。 如果服务器响应与本摘要不同，以服务器响应为准。

确认出席

确认信息包括参与者身份证件上显示的完整姓名、出生日期、国家身份证号或护照号码、紧急联系人、必须确认的个人资料图片，以及其他私人信息。参与者必须明确选择其 Clerk 图片、GitHub 头像或自定义上传；切勿根据可用图片推断其选择。建议参与者自行在交互式终端中运行以下命令，避免在 Agent 聊天中透露这些信息：

andes confirm

如果参与者明确要求 Agent 代为提交，请使用 andes schema --stage acceptance 获取最新模板，收集所有必填信息，切勿猜测；将信息存储在项目目录外、权限为 600 的临时文件中，并避免打印文件内容。dateOfBirth 使用 YYYY-MM-DD 格式，且必须是过去的真实日期。本次线下活动必须填写衬衫尺码。使用 andes --output json validate --stage acceptance --input /path/to/private-attendance.json 验证文件；成功响应不会回显文件内容。解决验证错误后，重新请求 现在提交这些私人出席信息？ 确认，然后运行：

andes --output json confirm --input /path/to/private-attendance.json

当 pictureSource 为 upload 时，询问参与者其电脑上的图片路径，并在 confirm 命令中添加 --picture /that/path/image.png。不要将图片字节复制到 JSON 文件或聊天中。CLI 接受最大 5 MB 的 JPEG、PNG 和 WebP 文件，会等待上传和验证完成，并在 stderr 上显示上传进度。自定义上传仅在确认出席后可用，且每 24 小时最多尝试五次。

命令完成后立即删除该文件。再次运行 status，并确认 requirements 阶段为 complete，然后再报告出席确认已完成。

与团队共同构建并发布进展

活动期间，使用这些命令前，请先阅读 andes project --help 和 andes team --help。如果项目命令不可用，请升级 CLI。使用 andes --output json team 和 andes --output json project 了解当前团队和提交内容。使用 andes --output json project updates 查看更新历史。任何成员都可以发布更新或编辑共享提交内容。使用团队名称作为项目名称；如有要求，请使用 andes --output json team rename --name "New team name" 重命名。切勿创建其他项目名称。

帮助团队确定下一步该做什么。当方向不明确时，询问能够消除不确定性的问题，而不是照着固定的问题清单逐一采访：

• 谁遇到了这个问题？他们现在是怎么解决的？
• 产品目前最需要实现什么？
• 团队遇到了什么阻碍？需要什么具体帮助才能解除阻碍？
• 我们做出了什么决定？有哪些证据支持这个决定？哪些内容被暂时搁置了？
• 下次演示时，人们实际可以试用什么？

在达到重要里程碑、改变方向、完成可运行的演示，或遇到导师可能帮忙解决的阻碍时，查看最新的共享更新；如果有新信息，建议再发布一条更新。在活跃工作会话中，取得重大进展后或大约一小时没有值得发布的更新时，再次检查。不要重复发布更新，也不要每次代码变更都打断团队。这项技能在活跃会话期间运行；它不会创建后台计时器。

如果参与者说“向导师／评委发送更新”，这就表示已授权准备并发布一条如实的更新。不要再次询问相同的许可。如果只是由 Agent 提议发布更新，请先提供草稿，并在发布前征得参与者同意。参与者在本次会话中授予的持续发布进度更新权限同样适用。内容应以已检查的工作和参与者的陈述为依据。区分已验证的结果、计划和未知事项。绝不要捏造用户测试、性能数据、影响或已完成的功能。

一条有用的 Markdown 更新应说明发生了哪些变化、团队为何作出该选择、哪些内容可用、遇到了什么阻碍、需要什么帮助、部署了什么、团队使用了哪些工具或服务，以及接下来要做什么。没有有用信息的部分可以省略。请附上相关的公开演示链接。不要包含机密、令牌、私人用户数据或保密信息。更新会与组织共享，并可能连同作者的公开姓名和时间戳一起公开展示在项目画廊中。发布后会保存一条供审核的记录；它不会发送电子邮件，也不保证导师会立即回复。

andes --output json project update --message "Terminamos el flujo y desplegamos la demo."
andes --output json project updates

默认直接输入文本。较长的 Markdown 也可使用 project update --file /path/to/update.md；文件为可选项。更新成功后，只会返回已保存的条目和总数。使用 project updates 查看完整历史记录。读取成功回执并核实已保存的内容后，才能声称更新已发布。如果写入超时，请先检查历史记录再重试，以免重复追加同一条更新。

活动设有四个赛道：Clima y Territorio（环境）、Movilidad y Transporte（交通运输）、Educación Escolar（学校教育）和 Seguridad（安全）。交通运输赛道涵盖利马市内的公共交通和客运，以及其他地区的区域交通连接、货运和配送。每个赛道的名额为当前团队总数的 25%，向上取整；活动最多容纳 36 支团队。即使名额减少，已选择的赛道仍然有效。使用 andes team 查看当前名额，使用 andes team track 选择赛道。

提交和维护项目

请阅读参与者指南 https://hacktheandes.com/guide 和交付条件 https://hacktheandes.com/participation-terms，了解当前活动说明。这些项目提交与参赛申请和挑战提交彼此独立。

项目提交必须包含以下四项交付物，并使用现有团队名称：

• 可正常运行的应用的在线部署 URL。
• 演示文稿 URL，例如 Canva、Google Slides 或代码编写的演示文稿。
• GitHub 仓库 URL，例如 https://github.com/team/project。读取 Git 远程地址以查找仓库；如果远程地址不明确，请向参与者确认。
• 一份 Markdown 描述，说明问题、目标用户、可正常运行的解决方案和已知限制。

参与者不能将自己的笔记本电脑连接到活动的演示设备。活动组织方会在自己的电脑上打开提交的链接。尽可能在退出登录或使用隐私浏览窗口的情况下检查这两个 URL。确认没有访问请求、个人登录依赖或本地文件。未实际检查前，不要声称链接可以访问。如果无法确认访问权限，请告知参与者还需检查什么。

鼓励参与者在四项交付物准备好后尽早提交。之后可以编辑同一份提交内容，包括一次只修改一个字段。只询问缺少的交付物。检查仓库和当前部署，以准备准确的 Markdown 描述。不要编造部署或演示文稿 URL。明确要求提交或更新项目，即表示授权执行该操作；否则，请展示准备好的提交内容并询问是否提交。

andes --output json project submit --deployment-url https://app.example --presentation-url https://slides.example --github-url https://github.com/equipo/proyecto --file /path/to/project.md
andes --output json project
andes --output json project submit --presentation-url https://new-slides.example

检查返回的已保存提交内容，包括每个已更改的字段。任何队友都可以编辑，因此请在操作前读取最新状态，并协调有冲突的编辑。如果最后一名成员离队或加入其他团队，原团队将解散，并释放其赛道名额和容量。活动组织方会在私有存档中保留该团队的提交及更新历史。该存档不属于公开画廊，也不会转移给新团队。

https://hacktheandes.com/projects 上的公开画廊起初处于隐藏状态，待活动组织方启用后才会开放。不要承诺画廊会在周日开放。项目发布后，其页面会包含描述、URL 和更新历史。提醒团队不要在这些字段中填写私人数据。

失败

如果返回 ok: false，请报告 error.code、error.message 和 requestId。展示最终摘要前，先解决本地验证失败。如果参与者的回答无需更改，可直接修正机械性问题；如果需要更改回答或同意内容，则应联系参与者。对于参赛申请、出席确认和挑战提交，最终批准后任何负载变更都会使该批准失效：展示更新后的摘要并再次征求批准。仅当 retryable 为 true 时，才重试未更改的失败请求。对于参赛申请、出席确认和挑战提交，重试前须重新取得提交批准。若身份验证失败，请返回验证参与者身份。保留请求 ID 以便支持人员查询，不要声称操作成功，也不要绕过失败状态。