From 214c44eebcf2e18161f643b4029d50b996503708 Mon Sep 17 00:00:00 2001 From: csh Date: Mon, 18 May 2026 15:43:48 +0800 Subject: [PATCH] :wrench: chore(markdown): add markdownlint baseline and lint fixes --- .markdownlint.json | 4 ++++ .markdownlintignore | 4 ++++ CONTRIBUTING.md | 1 + docs/python/style_guide.md | 4 ++-- docs/tsl/naming.md | 2 +- docs/tsl/syntax/04_values_and_literals.md | 4 +++- docs/typescript/code_style.md | 4 ++-- package.json | 4 +++- rulesets/index.md | 2 +- templates/prompts/meta/prompt-generator.template.md | 2 +- 10 files changed, 22 insertions(+), 9 deletions(-) create mode 100644 .markdownlint.json create mode 100644 .markdownlintignore diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 00000000..b077f0e1 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,4 @@ +{ + "default": true, + "MD013": false +} diff --git a/.markdownlintignore b/.markdownlintignore new file mode 100644 index 00000000..b96c989a --- /dev/null +++ b/.markdownlintignore @@ -0,0 +1,4 @@ +node_modules +tmp +reports +codex/skills/thirdparty diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8852d068..95795cee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,6 +19,7 @@ Follow `docs/common/commit_message.md` and use the required emoji/type mapping. Run the relevant checks before pushing: ```bash +npm run lint:md python -m unittest discover -s tests/cli -v python -m unittest discover -s tests -p "test_*.py" -v sh tests/templates/validate_python_templates.sh diff --git a/docs/python/style_guide.md b/docs/python/style_guide.md index 30b08acc..d697a0ac 100644 --- a/docs/python/style_guide.md +++ b/docs/python/style_guide.md @@ -3,8 +3,8 @@ 本 Playbook 的 Python 代码风格以 Google Python Style Guide 为基线（基于 PEP 8）： -- Google Python Style Guide: https://google.github.io/styleguide/pyguide.html -- PEP 8: https://peps.python.org/pep-0008/ +- Google Python Style Guide: +- PEP 8: ## 项目约定（Project Conventions） diff --git a/docs/tsl/naming.md b/docs/tsl/naming.md index b2ea29e7..4134fa27 100644 --- a/docs/tsl/naming.md +++ b/docs/tsl/naming.md @@ -40,7 +40,7 @@ Guide 对齐：通过名字的“形状”快速判断实体类型（类型/函 - 自定义标识符只使用本指南约定的 `PascalCase`/`snake_case`；`lowerCamelCase` 仅用于沿用内置/标准库/第三方 API 的既有命名。 -**大小写与关键字约定** +### 大小写与关键字约定 - TSL 语言大小写无关，但本指南仍要求按约定使用大小写以提升可读性；不要用仅大小写不同的名字区分不同实体；同一标识符在仓库中应保持一致写法。 - 所有语法关键字统一使用全小写书写，例如 diff --git a/docs/tsl/syntax/04_values_and_literals.md b/docs/tsl/syntax/04_values_and_literals.md index 31220cbe..4a9fb7c7 100644 --- a/docs/tsl/syntax/04_values_and_literals.md +++ b/docs/tsl/syntax/04_values_and_literals.md @@ -555,7 +555,9 @@ WriteLn(s[1:3]); s := %%ABC%%; ``` -上面这种写法在当前解释器里会报 `missing or invalid characters`。`%%` 原始字符串开头后面必须先跟一个空白分隔符，或者写成 `%%tag ` 这种“标识符 + 空白”形式。 +上面这种写法在当前解释器里会报 `missing or invalid characters`。`%%` +原始字符串开头后面必须先跟一个空白分隔符，或者写成 `%%tag` +这种“标识符 + 空白”形式。 代码块身份：反例 / 不可照写 diff --git a/docs/typescript/code_style.md b/docs/typescript/code_style.md index ab08d647..34403c0f 100644 --- a/docs/typescript/code_style.md +++ b/docs/typescript/code_style.md @@ -2,8 +2,8 @@ 本 Playbook 的 TypeScript/JavaScript 代码风格以 Google TypeScript Style Guide 为基线： -- Google TypeScript Style Guide: https://google.github.io/styleguide/tsguide.html -- TypeScript 官方手册: https://www.typescriptlang.org/docs/handbook/ +- Google TypeScript Style Guide: +- TypeScript 官方手册: ## 项目约定 diff --git a/package.json b/package.json index 7f6bf859..f36f34ff 100644 --- a/package.json +++ b/package.json @@ -2,9 +2,11 @@ "name": "playbook", "private": true, "devDependencies": { + "markdownlint-cli": "0.48.0", "prettier": "3.2.5" }, "scripts": { - "format:md": "prettier -w \"**/*.md\"" + "format:md": "prettier -w \"**/*.md\"", + "lint:md": "npx markdownlint-cli \"**/*.md\"" } } diff --git a/rulesets/index.md b/rulesets/index.md index 49571914..99ffce42 100644 --- a/rulesets/index.md +++ b/rulesets/index.md @@ -6,7 +6,7 @@ > - **AI 读取**：目标项目根目录的 `.agents/`，而非此处 > - **使用流程**： > -> ``` +> ```text > playbook/rulesets/tsl/ → [sync] → your-project/.agents/tsl/ ← AI 代理读取 > (模板源) (实际使用) > ``` diff --git a/templates/prompts/meta/prompt-generator.template.md b/templates/prompts/meta/prompt-generator.template.md index 85c9c2ae..46d10d63 100644 --- a/templates/prompts/meta/prompt-generator.template.md +++ b/templates/prompts/meta/prompt-generator.template.md @@ -84,7 +84,7 @@ ### 2. 迭代优化 -``` +```text 草稿 → 评估 → 修改 → 再评估 → ... → 定稿 ```