creator-hub/AGENTS.md

仓库规范

宪法（通用工程约束）

• 任何涉及文件的调研或修改，如果当前是 git 仓库，需要先同步远程提交到本地，避免调研过时问题。
• 基于 TDD 进行功能的开发与业务变更，单元测试覆盖率要保证 65% 以上。
• 任何时候我提出任何需求均需要理解并结构化复述后与我进行确认，避免理解偏差。
• 不要在代码里藏兜底逻辑来吞掉错误、隐藏问题。出了问题就应该让它爆出来，否则你永远找不到真实问题。
• 当一个问题出现时，不要用各种 small fix、针对性补丁来掩盖它。必须定位真实根因，彻底修复。在 bug 上糊纸只会让系统积累你不知道的危险暗病。
• 即使问题很难定位，也绝不要偷懒做表面修复。应该给项目增加充分的日志和可观测性，保证下次问题再现时你有足够信息去定位。问题无法修复时，只需要诚实告诉我信息不足、需新增日志，不要假装修好了。
• 始终注意在关键路径上给自己留足排查日志，确保每一个关键节点都是可追溯的。
• 当项目关键技术栈或产品方向发生变更时，同步更新 agents.md。文档必须随代码一起演进，不能让它变成过时的谎言。
• 大规模重构或实验性改动前，必须先切新分支。
• 不以维护向后兼容性为目标。对于已经废弃的代码路径，应直接移除，不再通过兼容层、回退机制或迁移方案予以保留。（注：开发阶段数据兼容豁免见下，本条针对代码路径。）
• 在充分满足当前需求的前提下，采用尽可能简单的实现方案。避免引入缺乏实际需求依据的抽象、配置项和间接层。
• 采用渐进式、分层的方式构建系统。首先完成能够端到端运行的最小版本，再基于稳定可用的产品逐步增加功能。不要以尚未成熟的复杂性取代已经可用的产品。
• 保持组件的模块化，并明确划分不同职责与关注点。
• 当成熟且维护良好的库能够降低整体复杂度或提高可靠性时，应优先采用。除非有明确理由，不要重复实现通用功能。
• 在自行实现功能或新增依赖之前，应优先评估项目现有依赖的能力。应先查阅相关文档与类型定义，不应未经确认就认定某个库不具备所需能力。
• 架构决策应着眼于长期演进。不要采用仅能解决当前问题、且预期需要在后续替换的权宜方案。
• 在设计解决方案之前，先研究成熟产品如何解决同类问题。优先采用经过验证的模式和约定，避免从零开始另行设计一套方案。

沟通方式

• 向使用者回报时，使用清楚直白的语言说明做了什么、结果如何。最终回复禁用术语、技术实现细节与工程腔。写法是：对一个聪明但没在看代码的人解释。
• 实际执行过程（思考、规划、写程序、除错、解决问题）保持完整的技术严谨度，这条规范只适用于对使用者的沟通方式。

回复风格

• 只写结论、实际改动、原因、验证结果
• 不描述推进动作，禁用「我先……再……」等叙述句式
• 不使用工程汇报腔（「落地」「落到」「推进」等类似用语）
• 直接、专业、去表演化
• 回复文字永远使用与对方相同的语系，专有名词维持英文
• 不使用口语化表达，说重点，简单明了
• 需要时搭配条列式与表格加强输出可读性

多选项决策

• 当方案有多个选项时，列出每个选项的优缺点，并明确指出推荐选项与原因。

Sub-Agent 使用时机

当任务符合以下任一条件时，直接 spawn sub-agent 分工执行，无需询问使用者：

• 任务可拆分为多个平行且无依赖的子任务
• 各子任务职责明确分离，合并执行会造成 context 混杂
• 大量结构相同的重复性任务（可用 spawn_agents_on_csv batch 执行）
• 各子任务需要不同的 model 配置或 sandbox 权限，例如：
  • 探索型任务使用轻量 model + read-only sandbox
  • 审查型任务使用高推理 model + read-only sandbox
  • 修改型任务使用执行导向 model + workspace-write sandbox

开发阶段原则

• 开发阶段仅关注业务功能：不实现访问限制、认证、网络隔离等安全策略，安全由用户自行把控。
• 开发阶段不做数据兼容：数据库 schema 可随时破坏性重建，不编写迁移兼容、存量回填或双写代码；网关与环境数据均可删除重来。
• 保持变更小而独立可评审，并附带覆盖该变更的最小相关检查。
• 使用下方已批准的技术栈；在栈内优先复用现有代码、标准库和平台原生能力，而非新增依赖或抽象。
• 在集成边界保持幂等性和向后兼容；文档化重试与失败行为。
• 永不提交密钥、生产凭据或个人账号数据。
• 引用上游项目时，记录其来源与许可证；除非许可证明确允许复用，否则须独立实现。

当前产品方向

• 当前业务范围与验收以 docs/plan01.md 为准：竞品分析、账号与大小号响应、环境与代理、评论线索和私信；先完成抖音完整流程，再完成小红书。
• 与旧探索规划或现有功能冲突时，以上述需求及使用者最新确认为准。自动响应按策略和 UID 冷却执行；人工发送逐次确认，两者不得混淆。自有账号互动与私信采用事件监听，不用轮询或 Mock 冒充实际能力。
• 上述内容是目标范围，不代表已经实现。平台能力缺口、新的业务歧义必须向使用者确认；禁止自行删减需求、隐藏失败或以未要求的通用框架扩大实现范围。控制面继续使用 Go，浏览器 gateway 使用 Python。
• 浏览器环境目标改为各机器 gateway 管理宿主机浏览器进程与 Xvfb，不再通过 Docker 创建浏览器环境；复用现有多机控制。采集结束（含失败、取消、超时）回收任务创建的临时资源，保留账号 Profile、正式结果和合法长期监听。评审、实施与验收见 变更评审、实施计划、验证文档。本轮仅交付文档，现有 Docker 实现尚未替换，具体契约与部署方案须批准后实施。

已批准的技术栈

Go 控制面

• 使用 Go 1.26、Fiber v3（HTTP 路由与服务生命周期）、Viper（配置）、Logrus（应用日志）、Cobra（可执行入口）。依赖版本由 go.mod 和 go.sum 精确锁定。
• 保留成熟的标准库集成，如反向代理，不重复造轮子；去 Docker 改造完成后移除浏览器链路的 Docker HTTP 客户端。net/http handler 跨越 Fiber 边界时，使用 Fiber 官方适配器。
• 创建局部 viper.New() 实例，只绑定支持的输入，显式应用默认值，并在产生网络、文件系统或 Docker 副作用前完成全部配置校验。未经评审的需求批准，不使用 Viper 全局单例、远程 provider 或热加载。
• 通过 Logrus 输出结构化 JSON 日志，保持 service 等稳定字段。可复用代码只返回错误，并在服务边界记录一次。
• 每个服务只保留一个最小化的 Cobra 根命令。仅当存在真实的运维工作流需求时，才添加子命令、持久化 flag、代码生成器或补全。
• 未经评审的需求批准，不添加 ORM、Redis、任务框架或另一套 HTTP/配置/日志/CLI 技术栈。

Python 浏览器 gateway

• 浏览器 gateway 使用 Python 3.12+；优先使用标准库 HTTP、进程管理、socket/ssl/asyncio 与显式输入校验，复用已有 CDP/WebSocket 能力。仅在实际需求明确且批准后新增锁定的浏览器依赖。
• 目标为每台 gateway 仅管理本机浏览器/Xvfb 生命周期、运行代次、Profile、临时资源、代理及页面动作，复用现有多机路由；账号身份必须在每次写操作前核对。当前代码仍依赖 Docker socket；实施批准后删除浏览器容器、卷、网络及镜像代码路径，不保留 Docker 回退。
• 任务清理必须核对节点、运行代次和资源归属，不能误删账号登录资料、正式素材或他人会话；控制面与 gateway 各自处理本机创建的临时文件，清理失败必须可见。
• Python 依赖必须写入锁定文件；不允许自动登录、任意 CDP、Cookie/验证码/密码回显或把不确定写结果转换为成功。

React 前端

• 使用 React 19、Vite 8、Refine 与 shadcn/ui、Tailwind CSS。在 web/package-lock.json 中锁定精确的已安装版本。
• 视觉体系由 CreatorHub 自有掌控：品牌 token 保留在项目主题与 Tailwind 配置中，导航/外壳保留在项目自有的 Layout 组件中。shadcn/ui 组件按需生成并纳入仓库自有代码，不引入 Ant Design、Arco、MUI 等其他组件体系。
• 图标统一使用 RemixIcon，不为差异化自创奇怪图标。
• 将启动、停止、回收等领域动作保留为显式动作；不得为迎合 Refine 惯例而伪装成通用 CRUD 更新。

UI 设计

默认收敛、克制、常规；尺寸与间距根据界面类型、信息密度、平台习惯、使用频率和视觉层级判断，不写死统一规格，也不主动放大。辅助入口、设置、开关、工具按钮不应抢视觉中心。常见功能必须使用大众通用、用户一眼可识别的图标隐喻，优先成熟图标库、系统图标或行业通用符号，不为差异化自创奇怪图标；自定义图标也必须保持常见轮廓、比例和语义。除非明确要求强调，否则优先用位置、分组、轻微颜色、hover、tooltip、分隔线和状态反馈表达层级，避免夸张尺寸、重色块、大圆角、厚边框、强阴影、装饰性渐变和营销页式布局。实现后必须与同屏元素对比检查，若显得突兀、过大、过重或破坏信息密度，应主动收敛。

验证与交付

• 功能完成后的功能验收不使用浏览器或其他自动化操作；只启动可联调的测试环境，并提供清晰的手工验证步骤，由使用者完成实际功能验证。
• 测试阶段默认不构建 Docker 镜像或容器；优先直接裸启动本地 Go control-plane 与 Vite 前端，保证本地服务可运行、可联调。
• 测试环境必须支持局域网手工验证：前端与本地 control-plane 监听 0.0.0.0，不得只绑定 127.0.0.1，并提供局域网访问地址。
• 开始任务前先定义完成标准。交付前依此验证，发现问题就修好再测，不把未完成的工作交回给使用者。只有确认完成，或遇到真正需要使用者介入的障碍时，才回报。
• 每个非平凡行为变更附带最小的回归测试，且该测试在无此变更时会失败。在信任与集成边界覆盖成功、校验、失败和兼容路径；单元测试覆盖率保证 65% 以上。
• 控制面变更必须通过 go test ./...、go vet ./...，并构建 ./cmd/control-plane；涉及并发、生命周期或共享状态的变更须运行 go test -race ./...。Python gateway 必须通过其非交互式单元测试与覆盖率检查；只有明确涉及 gateway/Docker/Compose 变更且获得使用者同意时，才执行 Compose 构建/健康检查。Docker 或 Compose 变更还须通过 docker compose config --quiet。
• 前端变更必须从 lockfile 安装、通过仓库的非交互式测试命令，并通过 npm --prefix web run build。主题、Layout、导航、资源动作或 data provider 的变更需要聚焦的交互覆盖，包括适用的错误与禁用状态。
• 除非 issue 明确批准契约变更，保持既有 API 与 Docker 生命周期行为不变。在 PR 中文档化任何状态码、载荷、配置、迁移、安全或重试方面的影响。