olonok69/cursor_code_ml_engineer

day — 打开和关闭工作日

为什么这是一个技能（skill），而不仅仅是一份文档。 “开始前拉取，结束后推送”这条规则在一份操作文档里待了好几个月，但在发布者机器上从未被遵循——没有任何记录显示曾进行过同步，因此也无法展示偏差。文档无法强制养成习惯，但可调用的例程可以。请阅读此文档来理解其结构，而非具体命令：每一个危险步骤都会先提出一个问题，如果答案不明确，就会停下来并询问用户。

data/ 下的共享记录只与最近一次同步保持同步，没有其它机制会提示同步。这里封装了两个关键时机：

day start     # 拉取团队最新内容，然后进行简短的导向简报
day end       # 发布今日工作，如果文档库有变动则标记知识图谱
day status    # 查看谁最近拉取/推送过（跨机器）；谁持有知识图谱接力棒
day baton     # 将发布者角色移交给另一台机器（用于出差、休假、交接）

以下所有内容均运行于 macOS、Linux 和 WSL 平台——纯 bash，无需 PowerShell。 脚本副本位于：ejemplos/metodologia/s3-sync/（从 config.env.example 开始——切勿部署真实的 config.env）。

步骤 1 — 找到同步文件夹并读取本机的角色

角色决定了你可以做什么。在写入任何桶之前先读取角色。

S3=""
d="$PWD"
while [ "$d" != "/" ]; do
  if [ -f "$d/data/changes/s3-sync/data-pull.sh" ]; then S3="$d/data/changes/s3-sync"; break; fi
  d="$(dirname "$d")"
done
if [ -z "$S3" ]; then echo "此仓库中没有共享记录同步（请在 <your-repo> 根目录下打开）。"; fi
sed -n '1,20p' "$S3/IDENTITY.md"

没有 IDENTITY.md，或内容已过时？重新生成——这是代理读取以了解其角色的文件，一份过时的卡片曾经引用了一个已被删除的 AWS 配置文件：

(cd "$S3" && ./identity.sh --write)

如果 S3 为空，请告知用户此仓库没有共享记录并停止。

步骤 2 — day start

1. ⚠️ 首先检查是否有未发布的本地工作——拉取操作可能会覆盖它们。 aws s3 sync 会在大小不同时进行传输，而不仅仅是远程文件更新时，因此拉取操作会用桶中较旧的副本替换本地编辑过的文件，并用旧名称重新创建您重命名的本地文件。不需要 --delete。

   (cd "$S3" && ./data-push.sh --root changes)   # 试运行——任何列出的内容都是本地独有的工作
   

   --root changes 将扫描范围限制为每天变动的唯一根目录（测量值从 212 秒降至 123 秒：有所优化，但非数量级提升）。此检查已足够；在发布时使用完整扫描。

   没有任何内容列出则继续。如果有内容列出，请说明是什么并提议先发布它；未经用户明确同意，不要跳过它直接拉取。

2. 拉取。 永远不要使用 --delete。脚本现在会保护您，但您必须阅读它输出的信息。

   (cd "$S3" && ./data-pull.sh --go)
   

   在应用任何变更之前，它会先进行试运行，将拉取会替换的每个本地文件的快照保存到 data/_prepull/<timestamp>/ 中，并列出它们。需要处理两种结果：

   • "⚠️ 将替换 N 个本地文件" — 向用户朗读该列表。 共享枢纽文件（STATUS.md, FOLLOWUPS.md, SHARP_EDGES.md, TEST_MAP.md, _RESUME_*.md）出现在其中意味着同事的副本将覆盖您的副本，而每一方都可能包含对方缺少的内容——这需要合并，而不是简单覆盖。 在执行其他操作之前，先比较快照文件与新文件：diff data/_prepull/<ts>/changes/STATUS.md data/changes/STATUS.md 要撤消整个拉取操作：cp -a data/_prepull/<ts>/. data/
   • 退出码 3，"存在大小写冲突的文件" — 桶中的两个对象仅大小写不同，在此机器上映射到一个文件。停止。 拉取操作会随机选择一个覆盖。首先删除桶中命名错误的键；工单文档的规范命名是小写 sst-NNNN.md（占位符模式）。

   凭据错误？在得出结论前先重新登录——过期的缓存令牌看起来和权限问题一模一样：aws sso logout && aws sso login。

3. 查看还有谁活跃： (cd "$S3" && ./activity.sh)

3b. 刷新工单状态表（几秒钟；≤ 5 行——将其粘贴到简报中）。可选：仅当项目从跟踪器和 Git 主机生成状态表时才需要。

(cd "$(dirname "$S3")/tools" && uv run -q --with openpyxl python ticket_status/sync.py)

发布者：从 Jira（状态、类型、链接）和 GitHub（PR、合并日期、首次发布）重写状态工作簿及其生成的 .md 文件。贡献者：生成相同的摘要，不写入任何内容——一个由两个写入者操作的二进制工作簿遵循“最后写入者获胜”原则。skipped — workbook is open → 请用户关闭该工作簿并重新运行。CANARY FAILED → 没有写入任何内容；先阅读运行日志。

3c. 最近 24 小时内的服务故障（约 1 分钟；仅计数，不下载——将分组行粘贴到简报中）：

T="$(dirname "$S3")/tools/evidence"
(cd "$T" && uv run -q --with boto3 python evidence.py discover --env dev --since 24h --list; \
            uv run -q --with boto3 python evidence.py discover --env stg --since 24h --list)

--list 存在的原因是首次实机运行发现 dev 环境在 24 小时内约有 240 个问题运行：如果使用下载发现模式，每天早上都会触发其自身的 --max-runs 保护。退出码 2 → 先重新登录。退出码 6 → 桶已停止保留旧版本：告知用户。要为某个分组收集证据，请使用 evidence 技能（fetch --doc <id>，或使用不带 --list 的 discover --since 2h）。

4. 导向——先看历史，再看状态。 最新的 data/changes/_RESUME_*.md（较旧的天数：_PENDING_*.md），然后是你负责领域的 data/changes/STATUS.md，然后执行 git fetch --all --prune 和 git status -sb。在设计任何东西之前，先使用 kg 技能查找现有成果——绝不要首先通过 data/changes/ 的 grep 来查找。

5. 仅适用于发布者机器（IDENTITY.md 中注明为 PUBLISHER）：检查接力棒和刷新队列。

   (cd "$S3" && ./publisher.sh status)
   bash data/knowledge-graph/kg_refresh.sh queue
   (cd "$S3" && ./delete.sh --check)            # 检查被删除但又重新出现的文件（仅报告）
   

   报告待处理内容；未经询问，不要启动刷新——这大约需要 100 次命名判断和整整一个小时，而一个命名了一半的图谱无法通过任何门控检查。

6. 用几行内容向用户做简报，然后停止。day start 准备好机器；它不选择工作内容。

步骤 3 — day end

1. 在发布之前先写下当天的工作： 将工单文档保存在 data/changes/<ticket>/ 下，更新 STATUS.md 中的一行，以及 FOLLOWUPS.md 中的任何后续内容。没有书面记录的工作与从未发生过的工作无法区分。

2. 预览，并阅读文件列表。 这是清理时刻——确保没有密钥、密码或任何不应进入共享记录的内容。

   (cd "$S3" && ./data-push.sh)
   

   ⚠️ 注意测试文件（fixture / issue / sample 目录下的 .docx/.pdf 文件）。提取器运行时会就地重新保存测试文件，而重新保存的测试文件可能保持其确切的字节大小，但其哈希值已发生变化。不要覆盖桶中的原始副本——改为从桶中恢复您的文件。

3. 发布。 永远不要使用 --delete。

   (cd "$S3" && ./data-push.sh --go)
   

   贡献者推送时报告跳过了 knowledge-graph/ 是正常的，不是错误——只有 refresh_queue/ 会从贡献者机器上传。

   ⛔ 如果推送退出码为 4——"拒绝：共享枢纽文件在桶中已更改" ——这意味着队友在本机上次同步后写了这些文件之一，并且我们的副本不同。aws s3 sync 没有合并功能，因此推送会覆盖他们的文件。向用户朗读指定的文件名，将每个文件与桶中的副本进行差异比较，然后合并。 不要自行使用 --allow-clobber——它仅适用于“用户已确认我们的副本取代了他们的副本”的情况，没有例外。

   (cd "$S3" && source ./config.env && \
     aws s3 cp "s3://$BUCKET/$PREFIX/changes/STATUS.md" - --profile "$PROFILE" | diff - ../STATUS.md)
   

   测量日期为 2026-09-18：同事结束他的一天四分钟后的一次推送，完全摧毁了他的整个 STATUS.md 节和他的活动日志——而此机器上之后看起来一切正常，因此它整整一天未被注意到。当我们的副本与桶中的副本字节完全相同时，此防护不会触发，因此我们刚刚拉取的文件永远不会发生冲突。

4. 如果工单文档发生更改，标记图谱，以便发布者知道需要重建：

   bash data/knowledge-graph/kg_refresh.sh request "<更改了什么及其重要性>"
   (cd "$S3" && ./data-push.sh --go)
   

5. 确认已成功落地： (cd "$S3" && ./activity.sh)——本机的推送时间应该显示为几分钟前。

day status

(cd "$S3" && ./activity.sh)          # 每台机器最后一次拉取/推送的时间
(cd "$S3" && ./activity.sh --log)    # 完整的事件流
(cd "$S3" && ./publisher.sh status)  # 谁可以重建并发布知识图谱

⚠️ 它报告的是已记录的内容。从未运行过此工具化脚本的机器不会显示任何内容；没有记录并不等于没有活动。

day baton — 移动发布者角色

只有一台机器发布知识图谱，因为 aws s3 sync 是“最后写入者获胜”且没有合并机制：两个发布者会静默地互相破坏对方手工编辑的社区名称。接力棒是一个存放在桶中的咨询锁，因此任一机器都可以检查它。

(cd "$S3" && ./publisher.sh status)
(cd "$S3" && ./publisher.sh release)            # 交出机器，先执行
(cd "$S3" && ./publisher.sh claim "why")        # 接收机器，后执行

接收机器还必须在 config.env 中设置 MACHINE_ROLE="publisher" 并重新运行 ./identity.sh --write，否则其代理会一直读到 CONTRIBUTOR 角色，并拒绝执行现在属于它的工作。claim --force 会覆盖已持有的接力棒——每次使用都必须先与用户确认。

所有分支都适用的规则

• 永远不要使用 --delete。 仅限发布者使用，需谨慎考虑，且只能在刚完成拉取后使用。
• 从共享存储中删除应使用 ./delete.sh（发布者），绝不要使用 aws s3 rm 或 --delete——否则其他机器会在下次推送时再次上传。
• 贡献者绝不要推送 knowledge-graph/。 工具会强制执行此规则；不要规避它。
• 在诊断访问错误之前先重新登录——该错误描述的是您缓存的令牌状态。
• 人类拥有外部操作的所有权。 此技能同步共享记录；它不推送分支、不打开 PR、不部署、也不向任何人发送消息。