🔧 chore(scripts): require flag-driven args
This commit is contained in:
@@ -56,13 +56,13 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python + Markdown（代码格式化）
|
||||
|
||||
```bash
|
||||
# Linux/macOS
|
||||
sh scripts/sync_templates.sh /path/to/project
|
||||
sh scripts/sync_templates.sh -project-root /path/to/project
|
||||
|
||||
# PowerShell
|
||||
.\scripts\sync_templates.ps1 -ProjectRoot C:\path\to\project
|
||||
|
||||
# Windows CMD
|
||||
scripts\sync_templates.bat C:\path\to\project
|
||||
scripts\sync_templates.bat -project-root C:\path\to\project
|
||||
```
|
||||
|
||||
**部署行为**：
|
||||
@@ -140,12 +140,13 @@ Layer 3: docs/ (权威静态文档)
|
||||
|
||||
| 你的情况 | 推荐方式 | 优势 |
|
||||
| -------------------------------- | ------------------------------- | ------------------------------- |
|
||||
| 新项目，需要持续同步更新 | **方式一：git subtree（推荐）** | 可随时拉取最新标准，版本可追溯 |
|
||||
| 新项目，需要持续同步更新 | 方式一：git subtree | 可随时拉取最新标准，版本可追溯 |
|
||||
| 只需要一次性引入，不常更新 | 方式二：手动复制快照 | 简单直接，无需 git subtree 知识 |
|
||||
| 只需要部分语言（如只要 TSL+C++） | 方式三：脚本裁剪复制 | 自动裁剪，只包含所需语言 |
|
||||
| 只需要部分语言（且希望快照也裁剪） | 方式三：脚本裁剪复制 | 快照只包含所需语言（更小） |
|
||||
| **不确定？** | **方式一：git subtree（推荐）** | 最灵活，后续可随时同步更新 |
|
||||
|
||||
**大部分情况推荐使用方式一（git subtree）。**
|
||||
说明：方式一可选择同步哪些语言规则到 `.agents/`，但 `docs/standards/playbook/` 快照仍是全量；方式三会裁剪快照本身。
|
||||
|
||||
---
|
||||
|
||||
@@ -159,7 +160,7 @@ git subtree add --prefix docs/standards/playbook \
|
||||
https://git.mytsl.cn/csh/playbook.git main --squash
|
||||
|
||||
# 2. 同步规则到项目根目录
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh tsl
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl
|
||||
|
||||
# 3. 提交
|
||||
git add .
|
||||
@@ -201,19 +202,19 @@ git commit -m ":package: deps(playbook): add tsl standards"
|
||||
2. **同步到项目根目录**（生成/更新 `.agents/<lang>/`、更新 `.gitattributes`）：
|
||||
|
||||
```bash
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl
|
||||
```
|
||||
|
||||
同步 C++ 规则集（同一份快照，不同规则集）：
|
||||
|
||||
```bash
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh cpp
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh -langs cpp
|
||||
```
|
||||
|
||||
一次同步多个规则集（推荐，减少重复备份 `.gitattributes`）：
|
||||
|
||||
```bash
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl,cpp
|
||||
```
|
||||
|
||||
> 说明：若项目根目录没有 `AGENTS.md`，`sync_standards.*`
|
||||
@@ -239,14 +240,14 @@ git commit -m ":package: deps(playbook): add tsl standards"
|
||||
|
||||
```bash
|
||||
git subtree add --prefix docs/standards/playbook https://git.mytsl.cn/csh/playbook.git main --squash
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh tsl
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl
|
||||
```
|
||||
|
||||
**旧项目**（已有 `AGENTS.md`）：
|
||||
|
||||
```bash
|
||||
git subtree pull --prefix docs/standards/playbook https://git.mytsl.cn/csh/playbook.git main --squash
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh tsl
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl
|
||||
```
|
||||
|
||||
旧项目的 `AGENTS.md` 不会被覆盖；如需指向 `.agents/`，请手动对齐内容。
|
||||
@@ -259,14 +260,14 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl
|
||||
#!/usr/bin/env sh
|
||||
set -eu
|
||||
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl,cpp
|
||||
# sh docs/standards/python/scripts/sync_standards.sh
|
||||
```
|
||||
|
||||
也可以直接一次同步多个规则集：
|
||||
|
||||
```sh
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl,cpp
|
||||
```
|
||||
|
||||
#### 目录约定（建议）
|
||||
@@ -303,16 +304,15 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
|
||||
- 脚本会从快照目录同步到项目根目录，并先备份旧文件（`.bak.*`）
|
||||
|
||||
建议固定使用 `--prefix docs/standards/playbook`，因为同步后的 `.agents/*/`
|
||||
会引用该路径下的标准快照文档（`docs/standards/playbook/docs/...`）。无参数时若已存在
|
||||
`.agents/<lang>/`，将按现有语言同步；否则默认 `.agents/tsl/`。如需同步 C++ 规则集，
|
||||
推荐直接运行：`sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp`。
|
||||
会引用该路径下的标准快照文档（`docs/standards/playbook/docs/...`）。同步时需显式指定
|
||||
语言参数（`-langs`），如需同步 C++ 规则集，推荐直接运行：
|
||||
`sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl,cpp`。
|
||||
|
||||
这样 clone 任意项目时都能直接读取规范文件，不依赖外部访问权限。
|
||||
|
||||
**同步脚本行为**（目标项目内的最终落地内容）：
|
||||
|
||||
- 覆盖/更新：`.agents/<AGENTS_NS>/`（默认 `.agents/tsl/`）
|
||||
- 自动识别：未传语言参数且已存在 `.agents/<lang>/` 时，按现有语言同步
|
||||
- 覆盖/更新：`.agents/<AGENTS_NS>/`（由 `-langs` 或 `AGENTS_NS` 指定）
|
||||
- 更新 `.gitattributes`：默认追加缺失规则（可用
|
||||
`SYNC_GITATTR_MODE=append|block|overwrite|skip` 控制）
|
||||
- 缺省创建：`.agents/index.md`
|
||||
@@ -362,19 +362,19 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
|
||||
- macOS/Linux：
|
||||
|
||||
```bash
|
||||
sh <PLAYBOOK_ROOT>/scripts/vendor_playbook.sh <target-project-root> tsl cpp
|
||||
sh <PLAYBOOK_ROOT>/scripts/vendor_playbook.sh -project-root <target-project-root> -langs tsl,cpp
|
||||
```
|
||||
|
||||
- PowerShell：
|
||||
|
||||
```powershell
|
||||
powershell -File <PLAYBOOK_ROOT>\\scripts\\vendor_playbook.ps1 -DestRoot <target-project-root> -Langs tsl,cpp
|
||||
powershell -File <PLAYBOOK_ROOT>\\scripts\\vendor_playbook.ps1 -ProjectRoot <target-project-root> -Langs tsl,cpp
|
||||
```
|
||||
|
||||
- Windows bat：
|
||||
|
||||
```bat
|
||||
<PLAYBOOK_ROOT>\\scripts\\vendor_playbook.bat <target-project-root> -langs tsl,cpp
|
||||
<PLAYBOOK_ROOT>\\scripts\\vendor_playbook.bat -project-root <target-project-root> -langs tsl,cpp
|
||||
```
|
||||
|
||||
**脚本会**：
|
||||
@@ -456,7 +456,7 @@ macOS/Linux 示例（目标项目的 `scripts/sync_standards.sh`）：
|
||||
#!/usr/bin/env sh
|
||||
set -eu
|
||||
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp
|
||||
sh docs/standards/playbook/scripts/sync_standards.sh -langs tsl,cpp
|
||||
|
||||
OVERLAY="docs/project/agents_overlay"
|
||||
if [ -d "$OVERLAY" ]; then
|
||||
@@ -490,7 +490,7 @@ if (Test-Path $overlay) {
|
||||
- 若新增"本 Playbook 未覆盖的语言"：再引入对应语言的标准仓库（subtree/vendoring 到
|
||||
`docs/standards/<lang>/`）
|
||||
- **代理规则**：
|
||||
- C++：运行 `sh docs/standards/playbook/scripts/sync_standards.sh cpp`（或
|
||||
- C++：运行 `sh docs/standards/playbook/scripts/sync_standards.sh -langs cpp`（或
|
||||
`& "docs/standards/playbook/scripts/sync_standards.ps1" -Langs cpp`），落地到
|
||||
`.agents/cpp/`（与 `.agents/tsl/` 并行）。
|
||||
- 其他语言：在目标项目增加 `.agents/<lang>/`（与 `.agents/tsl/`
|
||||
|
||||
Reference in New Issue
Block a user