project-builder

阶段 0：技能发现与必读内容

⚠️ 关键——UI 设计质量门槛： 如果项目会生成任何可视化 HTML 输出（仪表板、Web 应用、落地页、作品集，或用户会看到的任何页面），你必须在编写任何 HTML/CSS 之前，用 read_file 读取 ui-design 技能的 SKILL.md 并遵循其中要求。这不是可选项。project-builder 负责工程实现；ui-design 负责视觉质量（并会告诉你何时应选用 shadcn/ui、HeroUI 或 coss ui 之类的组件库，而不是手写）。跳过 ui-design 会导致产出千篇一律的 AI 垃圾内容。

A. 选择信息来源和工具。 调研和 API 文档请使用 Web 搜索。获取实时市场数据或执行外部操作时，请复用相关的已安装技能。使用前先阅读其 SKILL.md；若缺少所需技能，请使用 auto_install=false 搜索，并仅在用户批准后安装。只有在确认没有合适技能可处理该操作后，才编写自定义 API 代码；并根据当前官方文档核实端点和响应格式。

B. 阅读项目所涉及平台的规则。 这些规则位于参考资料中（而非系统提示词中），因此必须在编写代码前用 read_file 阅读。跳过这一步是出现 401、路径错误，以及“本地运行正常，预览却失败”问题的首要原因。

如果项目包含……	在阶段 2 之前使用 read_file 读取
任何外部 API 调用	config/context/references/sc-proxy.md
预览 / 仪表板 / Web 应用	config/context/references/preview-guide.md
定时任务	config/context/references/scheduled-tasks-guide.md
长时间运行的后台任务	config/context/references/background-tasks.md
超过 300 行的文件写入	config/context/references/tool-writing-guide.md
任何可视化 HTML 输出（仪表板、Web 应用、落地页、作品集）	ui-design 技能 SKILL.md——加载该文件，并遵循其中关于所有视觉决策（设计路径选择、颜色、排版、布局、动画，以及何时使用组件库）的要求。此技能是 UI 质量门槛；跳过它会导致产出千篇一律的 AI 垃圾内容。

---

阶段 1：设计

将模糊的需求转化为具体规格。 如果意图不明确，请提出一个问题。

架构决策树：

Periodic alerts/reports?  → Scheduled Task
Live visual interface?    → Preview Server (dashboard)
One-time analysis?        → Inline (no build needed)
Reusable tool?            → Script in workspace

对于中型及以上项目，请在编写代码前向用户说明：

1. 数据流——来源 → 处理 → 输出
2. 架构选择及原因
3. 成本估算——（每次运行成本）× 频率 × 30 = 月成本
4. 已知限制

UI 设计门槛（必需，阻塞执行——适用于可视化项目）： 如果架构选择为 Preview Server，或项目会输出用户可见的 HTML：

1. 现在用 read_file 读取 ui-design 技能的 SKILL.md（如果本会话中尚未读取），并选择一条设计路径（手工构建或组件库）。
2. 对于手工构建的 UI，请运行 Design Dials（见 ui-design 的 references/design-process.md），以确定 Surface、Accent、Typography 和 Aesthetic Family。
3. 在下方的阶段计划中加入 Design Dials 的输出行。 如果跳过此步骤，UI 看起来就会像千篇一律的 AI 生成内容。此门槛会阻塞后续操作——未完成此步骤前，不要进入阶段 2。

设计门槛： 对于多阶段工作，请先向用户提供简短的阶段计划。如果用户已经授权了明确且可逆的实现，就直接继续，无须再次征求相同的批准。仅在范围确实不明确、需要批准重大成本，或下一步不可逆/涉及外部操作（发布、发送、交易、删除）时才提问。处于活动状态的 Plan Mode 仍为只读模式，直到用户批准执行。

---

阶段 1.5：搭建项目骨架（可分享项目的必经步骤）

设计确认后，在编写任何代码之前，请按标准布局搭建项目骨架。从第一天起就能通过 community-publish 技能分享项目，无需后续迁移。

标准项目位置： output/projects/{slug}/

output/projects/{slug}/
├── project.yaml          # name, version (start 0.1.0), type, description, license, entry, env_required
├── PROJECT.md            # 4 required sections: What / Required env / How to start / Outputs / Troubleshooting
├── .env.example          # every env var the code reads, with placeholder values
├── .gitignore            # at minimum: .env, *.key, *.pem, __pycache__, node_modules
└── src/                  # all code lives here, NOT scattered
    ├── run.py            # type=task — first line MUST be: # -*- task-system: v3 -*-
    ├── server.py         # type=service
    ├── main.py           # type=script
    └── index.html / app.py + frontend  # type=preview

项目类型 → 入口映射：

架构选择	类型	入口路径
定时任务	task	src/run.py
预览服务	preview	src/index.html（静态）或 src/app.py
后台守护进程	service	src/server.py
单次运行工具	script	src/main.py

仅在以下情况跳过搭建骨架：

• 纯内联分析，不涉及持久化代码
• 修改现有的 output/projects/... 项目（保留其布局）
• 用户明确表示“只要把脚本扔到 /tmp 里”或类似要求

在阶段 2「构建」期间，维护项目骨架：

• 代码读取的每个新环境变量 → 在同一次编辑中添加到 .env.example
• 每次行为变更 → 更新 PROJECT.md
• 代码一律写在 src/ 之外（配置、测试夹具：放在项目根目录或 src/data/）

这样做的重要性： 已采用标准布局的项目只需一条命令即可发布。分散在 tasks/、output/scripts/、dashboards/ 等目录中的项目需要先通过 tidy_project() 迁移才能分享，而且用户通常不想凭记忆重新编写 PROJECT.md。

对于分散存放的现有代码： 调用 community-publish 技能 → 使用 tidy_project(any_dir) 重组，然后再发布。

---

API 费用与速率限制： 所有外部 API 调用都通过 sc-proxy 发起，按请求计费并执行速率限制。 开始设计前，请阅读 config/context/references/sc-proxy.md，了解价格表和限制。

• 估算费用：credits_per_request × requests_per_run × runs_per_day × 30
• 遵守速率限制：例如 CoinGecko 每分钟 60 个请求——每分钟轮询 10 种代币的任务没有问题；100 种则不行
• 优先使用批量端点，而非 N 次单独调用（例如，使用包含多个 id 的 coin_price，而不是分别调用 N 次）
• 纯脚本任务（不调用 API）：每次运行约 0 个 credits
• LLM 费用警告： 高端模型单次调用的费用可能超过 $0.10。不同模型等级的价格差异极大；对于相同的工作流，昂贵模型的费用可能是经济型模型的 100 倍以上。
• 必须按模型估算： 按模型拆分 LLM 费用（model_price_per_call × expected_calls_per_run × runs_per_day × 30），不要使用单一的通用数字。
• 仪表板自动刷新会消耗 credits——默认采用手动刷新，除非用户另有要求
• 费用保护： 如果预计每月 LLM 费用较高，请在实施前明确询问是否要限制每个调用方的费用。
• 按调用方跟踪（必需）： 每个代理请求都必须包含 SC-CALLER-ID（例如 job:{JOB_ID}、preview:{preview_id}、chat:{thread_id}），以便跟踪和限制用量。详情请参阅 config/context/references/sc-proxy.md § 调用方费用限制

数据可靠性： 原生工具 > 代理 API > 直接请求 > 网页抓取 > LLM 数字（绝不使用）。 铁律：脚本获取数据。LLM 分析文本。最终输出 = 脚本变量 + LLM 文字。

任务脚本可以直接导入技能函数：

from core.skill_tools import coingecko, coinglass  # auto-discovers skills/*/exports.py
prices = coingecko.coin_price(coin_ids=["bitcoin"], timestamps=["now"])

工具名称 = SKILL.md frontmatter 中的 tools: 列表。参见 build-patterns.md § 使用技能函数。

---

阶段 2：构建

每个组件都遵循以下循环：

Build one small piece → Run it → Verify output → ✅ Next piece / ❌ Fix first

构建项	验证方式	通过标准
数据获取器	运行并打印原始响应	内容非空、较新且合理
API 端点	curl localhost:{port}/api/...	JSON 正确
HTML 页面	preview_serve + preview_check	ok = true
任务脚本	python3 tasks/{id}/run.py	数字与来源一致
LLM 分析	使用脚本变量中的数字，而非 LLM 文本	使用模板模式

分层验证：

• 关键项（预览／启用前必须通过）：数据正确性、核心逻辑、不会崩溃
• 提示项（交付后可以修复）：样式、边缘情况提示、细微的 UX 润色

反模式：

• ❌ 什么都没运行就说“完成！”
• ❌ 写完 200 多行后才首次测试
• ❌ “应该能正常运行”

→ 详细模式：阅读 references/build-patterns.md

代码实践

• 先用 read_file，再用 edit_file——了解现有内容
• 修改时优先使用 edit_file，而非 write_file
• 使用 write_file 前先检查 ls——避免重复创建现有文件
• 大文件（>300 行）：拆分为多个文件，或先搭建骨架，再用 bash 注入内容
• 环境变量：使用 os.environ["KEY"]，将安装操作持久化到 setup.sh

仪表板 UX 默认设置（type=preview）

自行设定合理的默认值，并在首次加载时呈现真实数据。将筛选器视为可选的细化选项，供用户之后调整——绝不能让它们成为阻止初始视图显示的前置条件。按合理的间隔自动刷新。在任何内容显示之前，不要要求用户“点击以加载”“输入地址”或“选择符号”。

视觉设计质量（所有 HTML 输出的强制要求）： 如果已安装 ui-design 技能，编写任何 HTML/CSS 前都必须使用 read_file 读取其 SKILL.md 并遵循其中的要求。project-builder 负责工程工作流；ui-design 负责视觉质量。单独使用 project-builder 只能生成可用但视觉上平庸的输出。

---

平台规则

• Agent 工具只能通过工具调用使用，不能在脚本中导入
• 预览路径必须是相对路径（./path，而不是 /path）
• 在代码中将预览端口硬编码，不要从环境变量读取。 每个预览都在独立的 Pod 中运行，环境变量端口约定在不同 Pod 之间并不可靠。选择任意可用端口（例如 8765），直接将其写入应用，并将相同端口传给 preview(action="serve", port=...)。两者必须完全一致。
• 并发预览必须使用不同的 ID。 如果两个预览共享同一个 dir，较新的预览会自动终止较旧的预览（同目录替换规则）。现在，预览 ID 绑定到目录：即使标题变更，重新为同一个 dir 提供预览服务时也会保留相同的 ID，因此之前分享的 /preview/{id}/ 链接仍然有效。重新提供预览服务后，务必再次将 /preview/{id}/ 链接发送给用户。不要为了获取新 ID 而随意编造标题，也不要猜测 ID 的变体。
• 全栈 = 单个端口（后端提供 API 和静态文件）
• Cron 时间采用 UTC 时区 — 根据用户时区进行转换
• 预览服务与发布 → 阅读平台参考文档 config/context/references/preview-guide.md
• localhost API → 阅读 config/context/references/localhost-api.md
  • 任务脚本决定何时调用 Agent、传递哪些数据/上下文，以及使用哪个模型
  • 模式：脚本获取数据 → 判断是否值得关注 → 仅在需要时调用 LLM → 输出结果
• 在脚本中使用 LLM — 两种方案（详情见 references/build-patterns.md）：
  • OpenRouter（通过 sc-proxy）：轻量级，适用于摘要、翻译和文本格式化。直接调用 API，无 Agent 开销。
  • localhost /chat/stream：具备完整工具能力的 Agent。仅在 LLM 需要访问工具时使用。
• 数据模板规则：脚本负责数字，LLM 负责文字。最终输出由脚本变量中的数据和 LLM 的分析组成。用户看到的数字绝不能仅由 LLM 提供。
• API 费用与速率限制 → 阅读平台参考文档 config/context/references/sc-proxy.md
• 变现（可选）：使用 x402 技能，可以将你构建的任何 HTTP 服务转变为收费服务：在未改动的应用前添加反向代理网关，按调用/订阅（每周至每年）/终身使用/预付余额收取 Base 上的 USDC，并支持多种套餐。如果用户提到为项目收费、出售 API 访问权限或 Agent 间支付，请在构建阶段结束后阅读 skills/x402/SKILL.md，并使用 scripts/monetize.py 封装服务（对外暴露网关端口，而非上游端口）。 封装后的收费服务完整流程：对网关执行 preview(serve) → community-publish → publish_preview()（公开 URL）→ create_paid_service(..., pricing_options=[...]) → submit_for_review()（多套餐服务会通过 X-Pricing-Model 标头探测每个套餐的 402 金额）→ publish_service() → 在 Service Marketplace 上线。详情：community-publish SKILL.md § 收费服务列表。
• 始终在线的服务（长时间运行/已发布/收费）：Agent 机器在闲置时会自动挂起，自动更新重启会终止服务进程。任何必须保持全天候可访问的服务都需要：① 保活看门狗（定时重启服务的任务 — 见 skills/x402/SKILL.md 中的“始终在线可用性”）；② 将机器切换为手动更新模式（在 Web 控制面板中切换；Agent 只能在机器内读取此模式 — 如果读到“auto”，提醒用户切换开关，否则下一次平台更新会导致服务中断）。

---

阶段 3：调试

CHECK LOGS → REPRODUCE → ISOLATE → DIAGNOSE → FIX → VERIFY → REGRESS

• 先检查日志 ——任务日志、预览诊断信息、标准错误输出。如果日志显示了明确原因，直接跳到修复。
• 仅在日志不足时复现 ——亲自查看故障
• 隔离出问题的层（数据？逻辑？大模型？输出？前端？后端？）
• 修复根本原因，然后用相同的复现步骤验证。不要只修复，还要修复并确认。

三次失败规则： 同一种方法失败两次 → 停止 → 重新思考 → 向用户说明 → 改用其他方法。

→ 完整的调试流程：阅读 references/debug-handbook.md

---

快速检查清单

启动： ☐ 已明确意图 ☐ 已提出架构方案 ☐ 已估算成本 ☐ 用户已确认（进入阶段 2 前必须完成）

构建： ☐ 已测试每个组件 ☐ 数字与来源一致 ☐ 已处理错误 ☐ 预览正常（Web）

调试： ☐ 已检查日志 ☐ 已复现（或跳过——日志已足够） ☐ 已隔离问题层 ☐ 已找到根本原因 ☐ 已验证修复 ☐ 已检查回归问题