Imported from Yjcys/EchoGrid (
AutoDeploy/autoai/AGENTS.md). Install upstream withnpx skills add Yjcys/EchoGrid --skill autoai. Copyright stays with the author.
AGENTS.md
本文件是 AI 编码代理在本项目里的工作约定。新会话开始前先读：
docs/CURRENT_SCOPE.md- 本文件
项目权威 Scope
当前权威 scope 是 docs/CURRENT_SCOPE.md（2026-05-18）。
一句话：当前只围绕发布侧 Consumption / 矩阵平台发布链路工作，主实现域是 publishing/，真机执行层是平台 publisher + skills/mobile-control-adapter/。
旧日期的设计稿、prompt、plan 和 workflow 只作背景参考。它们可能包含旧阶段名、旧稳定性判断或已经被真实验收推翻的假设；不要把这些旧资料当作当前计划。
当前事实状态
已经实证跑通：
- OSS handoff 可访问：
oss://ml-multimodal/content-generate/publish-ready/。 - 对象存储 manifest 已能进入发布侧校验和本地缓存。
task_package已支持按图片数量选择单图或多图执行模式。- Xiaohongshu 多图真机发布已成功：样例任务
task_20260514_164147_001，4 张图，账号星音引力 / 27430532060。 - Douyin 属于当前发布侧范围，但还未完成与 Xiaohongshu 等价的真机发布闭环验收。
尚未视为无人值守闭环：
- ClawPaw HTTP / ADB forward 断连后的自动恢复和关键步骤重试。
- 真实定时发布：到点由 dispatcher 自动触发并完成结果写回。
- 真实切号发布：目标账号存在、切号成功、账号校验通过后再发布。
- 成功路径自动写回
publish-result.json、execution-result.json、account-state的端到端验收。 - Douyin 的对象存储 handoff、定时触发、真机执行、结果写回还需要按同一发布域契约补齐。
主链路
object-storage manifest
-> publishing.ingress
-> local cache
-> publishing.handoff.task_package.builder
-> runtime/publish-dispatch/items/<di>/dispatch-item.json
-> publishing.dispatch.local.cli
-> workers/local-publisher-worker/scripts/run_publish_task.py
-> platform publisher
-> skills/mobile-control-adapter
-> ClawPaw HTTP / ADB
-> real platform publish
-> publish-result.json + execution-result.json + account-state跑通命令
改动后至少运行与改动相关的测试和 lint。影响发布主链路时优先运行：
.venv/bin/python -m pytest -q \
tests/publishing/tos_ingress \
tests/publishing/task_package \
tests/integration/test_local_publisher_worker_flow.py \
skills/xiaohongshu-publisher/tests/test_executor.py \
skills/douyin-publisher/tests/test_executor.py \
skills/mobile-control-adapter/tests/test_clawpaw_executor.py
.venv/bin/ruff check \
publishing \
workers/local-publisher-worker \
skills/xiaohongshu-publisher \
skills/douyin-publisher \
skills/mobile-control-adapter \
tests如果改动面扩大，再跑：
.venv/bin/python -m pytest -q
.venv/bin/ruff check .不要在没有实际运行验证的情况下声称“已通过”。
路径占位符约定
文档示例统一用：
<PROJECT_ROOT>— 本仓库根目录。<USER_HOME>— 当前用户家目录。<CLAWPAW_REPO>— 手机端 ClawPaw fork 仓库，不在本仓内。
ClawPaw vision 配置：
- 默认
~/.clawpaw/config.yaml - 环境变量
CLAWPAW_CONFIG_PATH覆盖
对象存储环境
发布侧 ingress 只读取当前进程环境变量，不会自动加载 .env。排查桶访问失败时先确认这些变量在当前命令进程里是 set：
PUBLISHING_OBJECT_STORAGE_PROVIDERPUBLISHING_OBJECT_STORAGE_CACHE_ROOT或 provider-specific cache root- OSS:
OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET、OSS_ENDPOINT、OSS_BUCKET，OSS_REGION可选 - TOS:
TOS_ACCESS_KEY、TOS_SECRET_KEY、TOS_ENDPOINT、TOS_REGION、TOS_BUCKET
LLM_GATEWAY_API_KEY 不参与对象存储访问。launchctl setenv 只影响之后启动并继承 launchd 环境的 GUI 进程；当前 shell 跑命令前仍需要显式加载环境。详见 docs/workflows/object-storage-ingress.md。
工作边界
默认可以做：
- 读代码、读文档、跑测试、跑 lint。
- 修改当前任务明确要求的发布侧代码和测试。
- 写或更新当前 scope 相关文档。
- 为真实验收读取必要的
runtime/产物。
默认不要做：
- 不清理、删除、重命名
runtime/运行产物。 - 不改
references/skills/，除非用户明确要求。 - 不引入大依赖、CI、mypy、pre-commit 或格式化体系。
- 不执行
git push/git rebase/git reset --hard。 - 不输出、提交或泄露
.env、token、密码、AK/SK。
工程约束
1. 不写泛化兜底
ClawPaw / ADB 恢复、输入重试、发布按钮检测等逻辑必须有明确触发条件、最大重试次数、可观测错误和测试覆盖。不要用宽泛 catch、无限重试、随机 sleep 或无法解释的坐标堆叠掩盖问题。
2. mobile-control-adapter monkeypatch 约束
skills/mobile-control-adapter/scripts/mobile_control_adapter_clawpaw_executor.py 中依赖 requests、subprocess、socket、time 的函数，拆分到子模块前必须确认测试 monkeypatch 仍能覆盖入口 module 的同名对象。否则不要为“拆文件”牺牲测试可控性。
3. 频控写入时机
发布成功后才写 account-state。频控拒绝应进入 retry / rate-limited 状态，不要污染 publish_failed 统计。
4. publish_task.status = "archived_for_audit"
这是审计快照状态，不是正式调度入口。dispatcher / publisher 不应以该状态触发执行链路。
5. ClawPaw 媒体管道
device_session.connection.use_clawpaw_media_pipe 默认 false，当前正式路径仍走 ADB push + media scan。设 true 时必须 fail fast，因为 ClawPaw 端 file.download / media.scan 尚未作为本仓可依赖能力验收。
Review 要求
完成前必须自查：
- diff 是否只覆盖当前任务范围。
- 是否有密钥、账号敏感信息或
.env内容泄露。 - 是否误删、清理或污染运行产物。
- 失败路径是否会明确暴露，而不是静默吞掉。
- 测试是否覆盖核心失败模式。
复杂或跨模块任务可以使用 subagent 做并行审查；让 subagent 输出高信号结论、风险点、文件路径和建议补丁，不要把无关日志塞满主上下文。
沟通方式
- 默认中文，代码、命令、变量名保持英文。
- 结论先行。
- 模糊指令先按最合理假设推进；高风险才提问。
- 发现判断错了要暂停说明，不强行继续。
- 不夸大完成度；真实设备没验收就不要说已闭环。
推荐文档入口
- 当前 scope：
docs/CURRENT_SCOPE.md - 对象存储 ingress：
docs/workflows/object-storage-ingress.md - 本地 dispatcher：
docs/workflows/local-publish-dispatcher.md - Xiaohongshu operator：
docs/workflows/xiaohongshu-publishing-operator.md - 发布域说明：
docs/workflows/publishing-domain.md - 数据契约：
docs/schemas/ - ClawPaw 集成背景：
/Users/yjc/Desktop/AutoDeploy/clawpaw-integration.md
