📝 docs(readme): clarify project docs vs standards
This commit is contained in:
parent
c4efd8f274
commit
380228caca
137
README.md
137
README.md
|
|
@ -46,64 +46,109 @@ TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则
|
|||
|
||||
1. 在目标项目中首次引入：
|
||||
|
||||
```bash
|
||||
git subtree add \
|
||||
--prefix docs/standards/tsl \
|
||||
https://git.mytsl.cn/csh/tsl-playbook.git \
|
||||
main --squash
|
||||
```
|
||||
```bash
|
||||
git subtree add \
|
||||
--prefix docs/standards/tsl \
|
||||
https://git.mytsl.cn/csh/tsl-playbook.git \
|
||||
main --squash
|
||||
```
|
||||
|
||||
2. 后续同步更新：
|
||||
|
||||
```bash
|
||||
git subtree pull \
|
||||
--prefix docs/standards/tsl \
|
||||
https://git.mytsl.cn/csh/tsl-playbook.git \
|
||||
main --squash
|
||||
```
|
||||
```bash
|
||||
git subtree pull \
|
||||
--prefix docs/standards/tsl \
|
||||
https://git.mytsl.cn/csh/tsl-playbook.git \
|
||||
main --squash
|
||||
```
|
||||
|
||||
3. 目录约定（建议）
|
||||
#### 快速落地（最小 4 步）
|
||||
|
||||
目标项目推荐采用以下结构（Playbook 快照与项目文档分离）：
|
||||
在目标项目中按以下顺序执行即可完成落地（推荐固定使用 `--prefix docs/standards/tsl`）：
|
||||
|
||||
```txt
|
||||
.
|
||||
├── .agents/
|
||||
│ ├── index.md # 多语言代理规则集索引（缺省时由脚本创建）
|
||||
│ └── tsl/ # 从 Playbook 同步（仅覆盖该子目录）
|
||||
├── .gitattributes # 从 Playbook 同步
|
||||
├── docs/
|
||||
│ ├── standards/
|
||||
│ │ └── tsl/ # git subtree 快照（只读）
|
||||
│ │ ├── docs/ # common/ + tsl/
|
||||
│ │ ├── .agents/ # 标准代理规则快照
|
||||
│ │ ├── .gitattributes
|
||||
│ │ └── SOURCE.md # 记录来源版本/commit（项目自行维护）
|
||||
│ └── project/ # 目标项目自己的文档
|
||||
└── README.md # 说明遵循 standards
|
||||
```
|
||||
1. 引入标准快照（见上文 `git subtree add`）
|
||||
2. 同步到项目根目录（生成/更新 `.agents/tsl/`、更新 `.gitattributes`）：
|
||||
|
||||
根目录的 `.agents/tsl/` 与 `.gitattributes` 通过同步脚本获得：
|
||||
```bash
|
||||
sh docs/standards/tsl/scripts/sync_standards.sh
|
||||
```
|
||||
|
||||
- 说明：在 **本 playbook 仓库** 内脚本位于 `scripts/`；在 **目标项目** 里通过 `git subtree` 引入到 `docs/standards/tsl/` 后，脚本路径变为 `docs/standards/tsl/scripts/`。
|
||||
- 在目标项目里直接运行 Playbook 提供的脚本（子树快照里自带）：
|
||||
- `docs/standards/tsl/scripts/sync_standards.sh`（推荐）
|
||||
- `docs/standards/tsl/scripts/sync_standards.ps1`（推荐）
|
||||
- `docs/standards/tsl/scripts/sync_standards.bat`（推荐）
|
||||
- 脚本会从快照目录同步到项目根目录，并先备份旧文件（`.bak.*`）。
|
||||
3. 验收（任意满足其一即可）：
|
||||
|
||||
注：建议固定使用 `--prefix docs/standards/tsl`，因为同步后的 `.agents/tsl/` 会引用该路径下的标准快照文档（`docs/standards/tsl/docs/...`）。
|
||||
注：默认同步到 `.agents/tsl/`；如需指定规则集名称，可通过环境变量 `AGENTS_NS`（例如 `AGENTS_NS=tsl`、`AGENTS_NS=common`）。
|
||||
- 目录存在：`.agents/tsl/`
|
||||
- 规则入口可读：`.agents/tsl/index.md`
|
||||
- 标准文档可读：`docs/standards/tsl/docs/index.md`
|
||||
- `.gitattributes` 包含区块：`# BEGIN tsl-playbook .gitattributes` / `# END tsl-playbook .gitattributes`
|
||||
|
||||
这样 clone 任意项目时都能直接读取规范文件，不依赖外部访问权限。
|
||||
4. 将同步产物纳入版本控制（目标项目建议提交）：
|
||||
- `docs/standards/tsl/`（标准快照）
|
||||
- `.agents/tsl/`（落地规则集）
|
||||
- `.gitattributes`（managed block 更新）
|
||||
|
||||
同步脚本行为（目标项目内的最终落地内容）：
|
||||
#### 可选：项目包装脚本（多 playbook 串联）
|
||||
|
||||
- 覆盖/更新：`.agents/<AGENTS_NS>/`（默认 `.agents/tsl/`）
|
||||
- 更新 `.gitattributes`：默认只维护 `# BEGIN tsl-playbook .gitattributes` 区块（可用 `SYNC_GITATTR_MODE=overwrite|block|skip` 控制）
|
||||
- 缺省创建：`.agents/index.md`
|
||||
- 覆盖前备份：写入同目录的 `*.bak.*`（或 Windows 下随机后缀）
|
||||
- 不修改：`.gitignore`（项目自行维护）
|
||||
多语言项目建议在目标项目创建一个包装脚本（便于一键同步多个规则集）：
|
||||
|
||||
```sh
|
||||
#!/usr/bin/env sh
|
||||
set -eu
|
||||
|
||||
sh docs/standards/tsl/scripts/sync_standards.sh
|
||||
# sh docs/standards/python/scripts/sync_standards.sh
|
||||
# sh docs/standards/cpp/scripts/sync_standards.sh
|
||||
```
|
||||
|
||||
#### 目录约定（建议）
|
||||
|
||||
目标项目推荐采用以下结构（Playbook 快照与项目文档分离）：
|
||||
|
||||
```txt
|
||||
.
|
||||
├── .agents/
|
||||
│ ├── index.md # 多语言代理规则集索引（缺省时由脚本创建）
|
||||
│ └── tsl/ # 从 Playbook 同步（仅覆盖该子目录）
|
||||
├── .gitattributes # 从 Playbook 同步
|
||||
├── docs/
|
||||
│ ├── standards/
|
||||
│ │ └── tsl/ # git subtree 快照（只读）
|
||||
│ │ ├── docs/ # common/ + tsl/
|
||||
│ │ ├── .agents/ # 标准代理规则快照
|
||||
│ │ ├── .gitattributes
|
||||
│ │ └── SOURCE.md # 记录来源版本/commit（项目自行维护）
|
||||
│ └── project/ # 目标项目自己的文档（非语言标准：架构/运行/ADR/使用说明/业务约定等）
|
||||
└── README.md # 说明遵循 standards
|
||||
```
|
||||
|
||||
根目录的 `.agents/tsl/` 与 `.gitattributes` 通过同步脚本获得：
|
||||
|
||||
- 说明：在 **本 playbook 仓库** 内脚本位于 `scripts/`；在 **目标项目** 里通过 `git subtree` 引入到 `docs/standards/tsl/` 后，脚本路径变为 `docs/standards/tsl/scripts/`。
|
||||
- 在目标项目里直接运行 Playbook 提供的脚本（子树快照里自带）：
|
||||
- `docs/standards/tsl/scripts/sync_standards.sh`（推荐）
|
||||
- `docs/standards/tsl/scripts/sync_standards.ps1`（推荐）
|
||||
- `docs/standards/tsl/scripts/sync_standards.bat`（推荐）
|
||||
- 脚本会从快照目录同步到项目根目录，并先备份旧文件（`.bak.*`）。
|
||||
|
||||
注：建议固定使用 `--prefix docs/standards/tsl`，因为同步后的 `.agents/tsl/` 会引用该路径下的标准快照文档（`docs/standards/tsl/docs/...`）。
|
||||
注：默认同步到 `.agents/tsl/`；如需指定规则集名称，可通过环境变量 `AGENTS_NS`（例如 `AGENTS_NS=tsl`、`AGENTS_NS=common`）。
|
||||
|
||||
这样 clone 任意项目时都能直接读取规范文件，不依赖外部访问权限。
|
||||
|
||||
同步脚本行为（目标项目内的最终落地内容）：
|
||||
|
||||
- 覆盖/更新：`.agents/<AGENTS_NS>/`（默认 `.agents/tsl/`）
|
||||
- 更新 `.gitattributes`：默认只维护 `# BEGIN tsl-playbook .gitattributes` 区块（可用 `SYNC_GITATTR_MODE=block|overwrite|skip` 控制）
|
||||
- 缺省创建：`.agents/index.md`
|
||||
- 覆盖前备份：写入同目录的 `*.bak.*`（或 Windows 下随机后缀）
|
||||
- 不修改：`.gitignore`（项目自行维护）
|
||||
|
||||
#### 环境变量（可选）
|
||||
|
||||
同步脚本支持以下可选环境变量（默认值可满足大多数项目）：
|
||||
|
||||
| 变量名 | 默认值 | 说明 |
|
||||
| ------------------- | ------- | ------------------------------------------------------------------------------------------- |
|
||||
| `AGENTS_NS` | `tsl` | 规则集落地目录名：`.agents/<AGENTS_NS>/` |
|
||||
| `SYNC_GITATTR_MODE` | `block` | `.gitattributes` 同步模式：`block` 仅维护 managed 区块；`overwrite` 全量覆盖；`skip` 不更新 |
|
||||
|
||||
### 方式二：手动复制快照
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue