50 lines
3.9 KiB
Markdown
50 lines
3.9 KiB
Markdown
# SKG 营销内容工作台 Agent Rules
|
||
|
||
## Must Read First
|
||
|
||
- `.project.json` 是机器真源：公网链接、快捷登录、凭证引用都以它为准
|
||
- `RULES.md` 是人工规则和部署事实：启动命令、平台、域名、注意事项都写这里
|
||
- 工作看板全局规则是本项目的开发收口默认规则；本地规则缺失时按 `/Users/kangwan/Projects/code/20260317-rules-dashboard/RULES.md`、`SCHEMA.md`、`rules/03-Git约定.md`、`rules/04-版本发布规则.md` 补齐
|
||
- 不允许编造不存在的域名、账号、密码；未知就保持空白并明确标记待补充
|
||
|
||
## Development Ledger Contract
|
||
|
||
- 开发任务结束前必须执行并汇报 `git status -sb`
|
||
- 功能、修复、规则或部署元数据变更完成后，必须创建人工语义 commit；`auto-save` 只算安全快照
|
||
- 默认先在本地 Docker 完整验证：`./scripts/start-local-docker.sh` 后运行 `./scripts/verify-local-docker.sh`；用户明确确认“可以推送 / 上推 / 部署”前，不要 `git push`，也不要运行生产部署脚本。
|
||
- Gitea 是主远端，`origin` 必须指向 Gitea；只有在用户明确确认推送后，才把已验证的人工语义 commit 推送到 Gitea。
|
||
- 当前主分支为 `main`，Gitea 仓库为 `https://git.kang-kang.com/kangwan/20260512-skg-tk`
|
||
- `.memory/worklog.json` 是辅助日志，不代替人工语义 commit 和 Gitea 远端记录
|
||
- 不能推送时，必须说明当前分支、本地领先/落后数量、最新未推送 commit 和失败原因
|
||
|
||
## Deployment Metadata Contract
|
||
|
||
- 任何任务只要新增、删除或修改公网地址，必须在同一次任务里更新 `.project.json`
|
||
- `urls[]` 推荐显式写 `type`：`app`、`backend`、`docs`、`admin`、`repo`
|
||
- 项目专属的网页登录信息，如果允许放进仓库，就写 `.project.json.quick_login`
|
||
- 不能直接入库的敏感登录，不要伪造 `quick_login`，改为写 `.project.json.credentials` 引用
|
||
- 数据库密码、API Key、服务器 root 密码，不属于 `quick_login`
|
||
|
||
## Completion Gate
|
||
|
||
- 普通代码修改完成后，默认收口在本地 Docker 验证和本地 commit；生产推送 / 部署必须等用户明确确认。
|
||
- 部署完成后，不允许在 `.project.json` 缺少最新公网链接的状态下结束任务
|
||
- 部署完成后，必须同步更新 `RULES.md` 的部署事实
|
||
- 如果只更新了代码但没回写部署元数据，这个任务不算完成
|
||
|
||
## Source Analysis Contract
|
||
|
||
- 项目内源码解析页固定为 `docs/source-analysis.html`
|
||
- 该页面用于帮助用户把产品需求准确描述到源码位置：功能区、节点职责、数据模型、接口、变更影响都要能查到
|
||
- 任何改动只要影响产品理解、节点职责、界面行为、数据模型、API、运行方式或用户操作路径，必须在同一次任务里更新 `docs/source-analysis.html`
|
||
- 更新时至少补充“变更记录”，必要时同步更新源码结构地图、界面区域到源码、数据模型、接口地图、节点职责边界
|
||
- 不要把源码解析页接入主应用路由，除非用户明确要求；它默认是项目内独立 HTML 文档
|
||
|
||
## Media Asset UI Contract
|
||
|
||
- 任何图片 / 视频 / 抽帧 / 产品图 / 生成图 / 首尾帧 / 视频候选缩略图，不允许临时手写一套孤立交互；当前工作台新增媒体展示默认复用 `web/components/media-asset-tile.tsx`
|
||
- 所有媒体缩略图默认支持鼠标停留放大预览；预览层必须挂到顶层固定浮层，不能被滚动容器、面板或表格裁切
|
||
- 可删除的媒体素材必须显示删除入口；删除按钮、重新生成按钮、状态遮罩和悬停预览交互要在全项目保持一致
|
||
- 缩略图尺寸可按区域调整，但图片 / 视频必须可完整查看；需要裁切时必须仍能通过悬停预览看到完整素材
|
||
- 新增媒体板块验收时必须检查：悬停放大、删除入口、预览不被遮挡、图片完整性、视频预览、模型 / 状态标注是否与已有板块一致
|