📝 docs: simplify README + platform-agnostic tools + auto-create local rules

- Simplify docs/ section to grouped summary with pointer to docs/index.md
- Remove outdated performance metrics table
- Use cross-platform path examples throughout
- Make AGENT_RULES tool usage section platform-agnostic
- Auto-create AGENT_RULES.local.md on sync_rules (empty template)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
csh
2026-05-18 09:58:13 +08:00
co-authored by Claude Opus 4.6
parent 2431c9d3ad
commit 4ac86729d7
3 changed files with 30 additions and 39 deletions
+12 -38
View File
@@ -24,36 +24,17 @@ Playbook:工程规范与代理规则合集,当前覆盖:
`docs/` 目录是给开发者阅读的工程规范,约束代码写法、命名与提交信息。
- `docs/index.md`:文档导航(跨语言 common / TSL / C++ / Python / TypeScript / Markdown)。
- `docs/common/commit_message.md`:提交信息版本号规范(type/scope/subject/body/footer、可选 Emoji 图例、SemVer)。
- `docs/tsl/index.md`TSL canonical 入口(语法 / 金融 / 模块 / 函数检索四层)。
- `docs/tsl/code_style.md`TSL 代码结构、格式、`begin/end`
代码块、注释与通用最佳实践。
- `docs/tsl/naming.md`:TSL 命名规范(顶层声明、文件同名规则、变量/成员/property、常量、集合命名等)。
- `docs/tsl/syntax/index.md`TSL 语法手册。
- `docs/tsl/finance/index.md`:TSL 金融业务层入口(指标、选股、回测与业务流程问题)。
- `docs/tsl/modules/index.md`:TSL 模块层入口(pyTSL、微信消息、Python 互操作、回测框架)
- `docs/tsl/reference/index.md`TSL 函数检索入口(模块目录位于 `docs/tsl/reference/catalog/`)。
- `docs/tsl/toolchain.md`TSL 工具链与验证命令模板
- `docs/cpp/code_style.md`C++ 代码风格(C++23/Modules)。
- `docs/cpp/naming.md`:C++ 命名规范(Google 基线)。
- `docs/cpp/toolchain.md`C++ 工具链与验证命令模板。
- `docs/cpp/dependencies_conan.md`C++ Conan 依赖管理建议。
- `docs/cpp/clangd.md`clangd 补全配置建议(`.clangd`)。
- `docs/python/style_guide.md`Python 代码风格(Google 基线)。
- `docs/python/tooling.md`Python 工具链(black/isort/flake8/pylint/mypy/pytest/pre-commit)。
- `docs/python/configuration.md`Python 配置清单(落地时从 `templates/python/`
复制到项目根目录)。
- `docs/markdown/index.md`:Markdown 代码块与行内代码格式(仅代码格式化)。
- `docs/typescript/code_style.md`TypeScript 代码风格(Google 基线)。
- `docs/typescript/naming.md`TypeScript 命名规范。
- `docs/typescript/toolchain.md`TypeScript 工具链(typescript/prettier/eslint/vitest)。
- `docs/typescript/configuration.md`TypeScript 配置清单(tsconfig/eslint/prettier)。
- `templates/cpp/`C++ 落地模板(`.clang-format``conanfile.txt``CMakeUserPresets.json``CMakeLists.txt`)。
- `templates/python/`Python 落地模板(`pyproject.toml`
工具配置、`.flake8``.pylintrc``.pre-commit-config.yaml``.editorconfig``.vscode/settings.json`)。
- `templates/ci/`:目标项目 CI 示例模板(如 Gitea
Actions),用于自动化校验部分规范。
- `docs/index.md`:文档导航入口
- `docs/common/`跨语言规范(提交信息版本号
- `docs/tsl/`:TSL 规范(语法手册、金融业务、模块、函数检索、代码风格、命名、工具链)
- `docs/cpp/`C++ 规范(C++23/Modules、Google 基线、Conan、clangd
- `docs/python/`Python 规范(Google 基线、black/isort/flake8/pylint/mypy/pytest
- `docs/typescript/`TypeScript 规范(Google 基线、prettier/eslint/vitest
- `docs/markdown/`:Markdown 规范(仅代码格式化)
落地模板:`templates/cpp/``templates/python/``templates/ci/`
详见 `docs/index.md`
## templates/(项目架构模板)
@@ -144,13 +125,6 @@ Layer 3: docs/ (权威静态文档)
更多说明:`rulesets/index.md`
### 性能指标
| 指标 | 优化前 | 优化后 | 改善 |
| ------------- | ------- | ------ | ---- |
| .agents 规模 | ~500 行 | 167 行 | -67% |
| 持久化 tokens | ~12,500 | ~4,200 | -66% |
### 维护原则
**.agents/Layer 1)修改规则**
@@ -199,7 +173,7 @@ TSL 相关问题直接查阅 `rulesets/tsl/index.md` 与 `docs/tsl/`。
- `project_root`:目标项目根目录。
- `deploy_root`:相对于 `project_root` 的项目内目标目录。
- 外部 clone 出来的 Playbook 路径(如 `/opt/playbook``C:/tools/playbook`):只是执行部署脚本的位置,不是部署目标。
- 外部 clone 出来的 Playbook 路径(如 `/opt/playbook`):只是执行部署脚本的位置,不是部署目标。
以 TSL 为例,Playbook 在项目内的默认部署根是 `docs/standards/playbook`;如果你把 `deploy_root` 改成 `custom/playbook`,则部署结果会落到 `<project_root>/custom/playbook`,文档和脚本入口也会跟着变成 `custom/playbook/docs/...``custom/playbook/scripts/...`