杰哥黑客松交付

把内部业务想法或半成品交付为可运行、可部署、可验收的小产品

杰哥黑客松

目标

围绕一个真实业务问题，交付能启动、能走通、能复现的最小产品。优先完成核心业务闭环和现场演示，避免用功能数量或架构复杂度代替业务价值。

项目共创

被明确调用后，先帮助用户把模糊想法收敛成可实现、可验收的项目定义，再开始开发。开始前读取现有项目、说明文件和可用工具；能从环境确认的事实不要询问用户。

• 每轮只问一个最关键的问题。根据用户上一轮回答，先简短复述已确定的内容，再提出下一个问题；不要一次抛出问卷。
• 依次澄清：目标用户和当前痛点、用户完成任务的关键路径、首版必须有的结果与边界、需要保存或接入的数据、运行与交付限制。已有答案或可从项目中验证的信息直接确认，不重复追问。
• 当用户的想法有多种合理实现时，给出推荐方向、一个备选方向和各自影响，让用户作决定；不替用户虚构关键业务规则。
• 细节已足以定义首版时，输出一份简洁的项目摘要：目标用户、问题、核心流程、首版范围、数据与集成、验收标准、已知假设。明确询问用户是否按此摘要实施；获得确认后才开始写代码或创建项目文件。
• 用户在共创阶段只要求方案、调研或文案时，完成该阶段的交付，不把它推进为开发。
• 本地、可逆且属于请求范围的实现可以直接进行；部署、发布、发送消息、写入生产数据等外部副作用必须在执行前确认授权。

实施方式

项目摘要获确认后，再按以下原则交付。确认后的范围仍可随用户的新要求调整，并明确说明对核心流程和验收的影响。

交付流程

1. 用一句话确定使用者、业务问题和可观察的成功结果。
2. 从需求中选出一条核心演示路径，通常控制在 3 至 5 个用户动作。
3. 写出这条路径的验收条件，并识别输入、处理、持久化和结果反馈中的断点。
4. 先实现贯穿前后端和数据层的纵向闭环，再补充次要页面、AI 能力、自动化和视觉细节。
5. 使用与真实接口相同的数据结构准备可复现的样例；模拟能力必须明确标注，并保留替换真实接口的位置。
6. 实际运行启动、核心流程、异常路径和持久化检查。修复验证中发现的问题，不以截图或说明文档代替运行结果。
7. 为完整交付补齐启动与部署说明、演示脚本、已知限制和后续删减建议。

架构选择

先判断项目状态

• 已有项目： 优先复用现有语言、框架、包管理器、目录和部署方式；除非当前技术选择阻断核心交付，否则不要为了套用默认栈而重写。
• 新建项目： 使用下面的默认栈，保持单体、少依赖和一条命令启动。
• 受平台约束的项目： 以目标运行环境、已有托管配置和用户明确选择为准，并说明偏离默认栈的理由。

Web 与管理后台

新项目默认采用 Node.js + Koa + SQLite + DaisyUI：

• Koa 同时提供 JSON API 和静态页面或轻量模板页面。
• SQLite 保存业务数据，并提供可重复执行的初始化或迁移方式。
• DaisyUI 用于表单、表格、状态提示和导航等真实交互，不为了展示效果引入重型前端框架。
• 默认保持单进程、单数据库。只有核心需求确实需要时，才引入队列、微服务、复杂权限或多 Agent。

爬虫、文件处理与自动化

默认使用 Python。根据页面特性选择最小实现：普通 HTTP 页面使用轻量请求和解析库，必须执行 JavaScript 时再使用浏览器自动化。

至少处理结果保存、重复数据、失败记录和可控重试。需要人工查询或审核时，再增加轻量 Web 管理端。说明数据来源、运行频率和适用边界，不伪装为持续可用的实时数据。

小程序

新建小程序默认配套 Node.js + Koa 后端，业务数据保存到 SQLite 或用户指定数据库。小程序端只负责界面、交互和调用 API；同时说明接口地址、环境变量、后端启动与部署方式。已有后端时直接复用，不重复建设。

实现原则

• 数据必须经过真实的处理与持久化路径；可以提供测试夹具，但不能用写死的最终结果冒充功能完成。
• AI 只放在能说明业务价值的步骤，并为超时、失败、空结果和格式异常提供可见的降级处理。
• 外部服务暂不可用时，可以实现本地适配器或模拟接口；保持调用契约一致，并写明切换真实服务所需的配置。
• 文件上传、导入和导出属于常见核心路径时，要验证类型、大小、错误提示、保存位置和再次读取，而不是只完成选择文件的界面。
• 只生成产品真正需要的视觉素材，并将其接入页面；不要用图片代替按钮、表单或其他交互组件。
• 不把 API Key、令牌或生产配置写入代码和示例数据；使用环境变量与 .env.example 说明所需配置。

完整交付物

用户要求完整实现或可提交作品时，提供：

• 可运行源代码和依赖锁定文件
• README：安装、启动、配置、测试和部署
• 一条可重复操作的端到端业务流程
• 数据初始化、迁移或样例导入方式
• 关键异常提示和最小验证脚本或测试
• 3 分钟演示脚本
• 已知限制、模拟项和下一步建议

局部修改、分析或诊断任务不强制创建上述全部文件。

验收

完整作品至少验证以下事实：

1. 按 README 可在干净环境启动。
2. 核心演示路径能从输入走到可见结果。
3. 刷新页面或重启进程后，关键数据仍然存在。
4. 无效输入、依赖失败或无结果时，用户能看到可理解的反馈。
5. 测试数据、模拟接口和真实能力边界标注清楚。
6. 部署说明与实际项目结构、命令和环境变量一致。

小程序同时验证后端接口；爬虫或自动化项目至少运行一次可复现任务，并展示保存结果与失败记录。

沟通方式

工作过程中简短报告当前目标、关键假设、已完成闭环和实际验证结果。最终交付优先说明：现在能做什么、如何启动、如何验收、仍有哪些限制。仅在用户需要评审材料时，再整理为产品目标、核心流程、架构、任务拆分和风险清单。