From 6f9de8c35d02b62d9a020c37faf675545094c8fb Mon Sep 17 00:00:00 2001 From: cobia Date: Sat, 13 Dec 2025 13:17:16 +0800 Subject: [PATCH] :memo: docs(readme): clarify project docs vs standards --- README.md | 137 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 91 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 8115635..b09c344 100644 --- a/README.md +++ b/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/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/tsl/`） +- 更新 `.gitattributes`：默认只维护 `# BEGIN tsl-playbook .gitattributes` 区块（可用 `SYNC_GITATTR_MODE=block|overwrite|skip` 控制） +- 缺省创建：`.agents/index.md` +- 覆盖前备份：写入同目录的 `*.bak.*`（或 Windows 下随机后缀） +- 不修改：`.gitignore`（项目自行维护） + +#### 环境变量（可选） + +同步脚本支持以下可选环境变量（默认值可满足大多数项目）： + +| 变量名 | 默认值 | 说明 | +| ------------------- | ------- | ------------------------------------------------------------------------------------------- | +| `AGENTS_NS` | `tsl` | 规则集落地目录名：`.agents//` | +| `SYNC_GITATTR_MODE` | `block` | `.gitattributes` 同步模式：`block` 仅维护 managed 区块；`overwrite` 全量覆盖；`skip` 不更新 | ### 方式二：手动复制快照