Cursor 帮助文档 · 完整代码约定

所有帮助文档（docs/md_cursor/）里的 Python、Bash、Patch、Env、Yaml 均必须是完整代码，不再贴片段。

双端同步：程序（scripts_* / patches_*）与文档（md / html）在 Windows 与 207 必须完全同步。
执行位置：改配置、打补丁、验收脚本 → 在 207 上用 /usr/bin/python3 跑。
目录规则：按文档名分子目录；共用程序可复制到多个文档子目录。

目录结构

文档名去掉 _cursor.md 后，作为子目录名：

text

/opt/workbuddy/
├── dify_api.py
├── scripts_cursor/
│   ├── 00_部署_workbuddy到207.py          # 同步工具（根上）
│   ├── _config.py / _bootstrap.py ...     # 根上副本（给同步脚本用）
│   ├── 作业1_带工具调用的Agent_服务器状态/
│   │   ├── _config.py                     # 本目录可用
│   │   ├── 作业1_01_部署模拟服务.py
│   │   └── ...
│   ├── 作业3_追踪Agent工具调用验收/
│   │   ├── Langfuse_01_打langfuse_trace补丁_修改后.py   # 与连接专题共用
│   │   └── ...
│   ├── Langfuse_连接Dify专题/
│   │   └── Langfuse_01_打langfuse_trace补丁_修改后.py   # 同一程序的另一份
│   └── ...
├── scripts_bash_cursor/<文档名>/xxx.sh
├── patches_cursor/<文档名>/xxx
└── docs/{md_cursor,html_cursor}/

目录	类型
`/opt/workbuddy/scripts_cursor/<文档名>/`	完整 Python
`/opt/workbuddy/scripts_bash_cursor/<文档名>/`	完整 Bash
`/opt/workbuddy/patches_cursor/<文档名>/`	完整补丁 / OpenAPI / env

换环境：改任意文档子目录里的 _config.py（或根上 _config.py），改完后请保持各副本一致，再执行同步。

怎么运行（207）

bash

# 按文档子目录执行
/usr/bin/python3 /opt/workbuddy/scripts_cursor/作业1_带工具调用的Agent_服务器状态/作业1_05_对话验收.py

/usr/bin/python3 /opt/workbuddy/scripts_cursor/作业4_成本熔断/作业4_02_验收成本熔断.py

/usr/bin/python3 /opt/workbuddy/scripts_cursor/作业5_vLLM健康检查Agent/作业5_05_对话验收.py

# 封装
bash /opt/workbuddy/scripts_bash_cursor/workbuddy_run.sh \
  作业1_带工具调用的Agent_服务器状态/作业1_05_对话验收.py

Windows 同步到 207

bash

# 程序 + 文档全量同步（推荐）
python scripts_cursor/00_部署_workbuddy到207.py

# 只同步 md/html
python scripts_cursor/00_部署_workbuddy到207.py --docs-only

也可：

bash

python scripts_cursor/完整代码约定/00_部署_workbuddy到207.py

文档里怎么写路径

完整程序：/opt/workbuddy/scripts_cursor/<文档名>/xxx.py + 全文嵌入
完整脚本：/opt/workbuddy/scripts_bash_cursor/<文档名>/xxx.sh + 全文嵌入
完整补丁：/opt/workbuddy/patches_cursor/<文档名>/xxx + 全文嵌入

共用程序在多个文档中引用时，路径写当前文档对应的那份子目录（内容相同）。

维护工具（Windows）

bash

python tools/reorganize_by_doc.py          # 按文档名重组（一般只需一次）
python tools/update_paths_after_reorg.py   # 按子目录改写 md/html 路径
python scripts_cursor/00_部署_workbuddy到207.py