From 8b93311caed4d4dac71853b120ddbbe58a429873 Mon Sep 17 00:00:00 2001 From: csh Date: Sun, 21 Jun 2026 17:04:50 +0800 Subject: [PATCH] :memo: docs(tsl): clarify syntax constraints and enhance test infrastructure - Add TSF file naming constraint to syntax/02_core_model.md - Clarify semicolon rules: syntax facts vs style preferences - Separate control flow end semicolon rules (syntax allows both) - Add function body semicolon requirements to syntax/05_functions_and_calls.md - Move style preferences to code_style.md (control flow end semicolons) - Remove cross-references from syntax docs to maintain independence - Enhance Gitea workflow emoji for better CI output readability - Fix CI test path from tests/ to test/ - Organize agent test results under test/agent/result/ directory - Add complete Chinese translation of test cases (test_cases_zh.md) - Clean up .gitignore to use unified test/agent/result/ directory - Remove obsolete agent test artifacts (REPORTS_LOCATION.md, old results) Co-Authored-By: Claude Opus 4.6 (1M context) --- .gitea/workflows/standards-check.yml | 8 +- .gitea/workflows/test.yml | 20 +- .gitea/workflows/update-thirdparty-skills.yml | 7 +- .gitignore | 7 +- README.md | 123 +- SKILLS.md | 166 +- docs/tsl/code_style.md | 22 +- docs/tsl/index.md | 99 +- docs/tsl/naming.md | 24 +- docs/tsl/reference/catalog/base.md | 54 +- .../{03_date_basic.md => 02_date_basic.md} | 24 + .../catalog/base/02_simple_conversion.md | 29 - ...datetime_parts.md => 03_datetime_parts.md} | 0 ...oundaries.md => 04_datetime_boundaries.md} | 0 ..._relations.md => 05_datetime_relations.md} | 0 ...e_predicates.md => 06_range_predicates.md} | 0 ...8_range_getters.md => 07_range_getters.md} | 0 .../{09_range_span.md => 08_range_span.md} | 0 .../{10_time_shift.md => 09_time_shift.md} | 0 ...me.md => 10_compose_decompose_datetime.md} | 0 ...tetime_recode.md => 11_datetime_recode.md} | 0 ...on.md => 12_datetime_format_conversion.md} | 0 ...sion.md => 13_wide_datetime_conversion.md} | 0 ...5_string_common.md => 14_string_common.md} | 0 ..._predicates.md => 15_string_predicates.md} | 0 ...rocess.md => 16_string_replace_process.md} | 0 ...array.md => 17_string_array_and_repeat.md} | 16 +- .../catalog/base/{21_byte.md => 18_byte.md} | 0 .../base/{22_phonetic.md => 19_phonetic.md} | 0 docs/tsl/reference/catalog/base/19_repeat.md | 19 - .../catalog/base/20_multibyte_language.md | 31 - .../catalog/base/{23_regex.md => 20_regex.md} | 0 ...4_multilanguage.md => 21_multilanguage.md} | 26 + ...5_path_filename.md => 22_path_filename.md} | 0 .../{26_array_basic.md => 23_array_basic.md} | 0 ...dex_length.md => 24_array_index_length.md} | 0 ...ure.md => 25_array_sort_and_operations.md} | 30 +- .../{29_array_crud.md => 26_array_crud.md} | 0 .../reference/catalog/base/28_array_sort.md | 31 - docs/tsl/reference/catalog/datawarehouse.md | 55 +- .../datawarehouse/01_system_param_keys.md | 18 - ...aram_names.md => 01_system_param_names.md} | 0 ...{03_multi_market.md => 02_multi_market.md} | 0 .../datawarehouse/{04_time.md => 03_time.md} | 0 .../{05_predicates.md => 04_predicates.md} | 18 + ...able.md => 05_intraday_and_after_close.md} | 18 + .../catalog/datawarehouse/06_intraday.md | 18 - ...eries_stats.md => 06_time_series_stats.md} | 0 ..._data.md => 07_transaction_detail_data.md} | 0 ...lds.md => 08_transaction_detail_fields.md} | 0 ...2_market_sector.md => 09_market_sector.md} | 0 ...{13_quote_series.md => 10_quote_series.md} | 0 .../catalog/datawarehouse/11_query_polling.md | 27 - ...functions.md => 11_reference_functions.md} | 0 ...param_access.md => 12_sys_param_access.md} | 13 + ...statement_types.md => 13_reinstatement.md} | 29 +- .../{18_cycle.md => 14_cycle.md} | 0 .../{19_financial.md => 15_financial.md} | 0 ...and_fetch.md => 16_selection_and_fetch.md} | 27 + .../17_reinstatement_base_date.md | 27 - .../{21_wizard.md => 17_wizard.md} | 0 ...rd_n_periods.md => 18_wizard_n_periods.md} | 0 ...3_wizard_n_days.md => 19_wizard_n_days.md} | 0 ...{26_wizard_range.md => 20_wizard_range.md} | 0 ...ermediate.md => 21_wizard_intermediate.md} | 59 + ..._n_quarters.md => 22_wizard_n_quarters.md} | 0 ...{29_wizard_today.md => 23_wizard_today.md} | 0 .../24_wizard_n_days_intermediate.md | 29 - ...ate.md => 24_wizard_today_intermediate.md} | 0 .../catalog/datawarehouse/25_wizard_legacy.md | 30 - .../datawarehouse/31_condition_predicates.md | 18 - docs/tsl/reference/catalog/resource.md | 5 +- .../catalog/resource/02_file_access.md | 17 + .../resource/{08_process.md => 07_process.md} | 0 .../catalog/resource/07_wide_byte.md | 17 - ...local_resource.md => 08_local_resource.md} | 0 docs/tsl/reference/catalog/system.md | 12 +- .../reference/catalog/system/01_data_type.md | 38 + docs/tsl/reference/catalog/system/03_copy.md | 18 - ...{04_global_cache.md => 03_global_cache.md} | 0 .../system/{05_random.md => 04_random.md} | 0 .../{07_expression.md => 05_expression.md} | 0 .../catalog/system/06_conditional.md | 20 - ...{09_tsl_lib_path.md => 06_tsl_lib_path.md} | 0 ...assertion.md => 07_error_and_assertion.md} | 31 +- .../reference/catalog/system/08_profiler.md | 29 - docs/tsl/syntax/00_agent_index.json | 218 ++ docs/tsl/syntax/02_core_model.md | 4 + docs/tsl/syntax/05_functions_and_calls.md | 4 +- docs/tsl/syntax/07_control_flow.md | 7 +- docs/tsl/syntax/index.md | 114 +- docs/tsl/toolchain.md | 12 +- playbook.toml.example | 86 +- rulesets/cpp/index.md | 7 - rulesets/markdown/index.md | 3 +- rulesets/python/index.md | 7 - rulesets/tsl/index.md | 152 +- rulesets/typescript/index.md | 7 - scripts/main_loop.py | 2 - skills/README.md | 91 +- templates/AGENTS.template.md | 4 +- templates/AGENT_RULES.template.md | 309 +- templates/README.md | 419 +-- .../prompts/meta/prompt-generator.template.md | 126 - .../prompts/system/agent-behavior.template.md | 2 +- {tests => test}/README.md | 0 test/agent/README.md | 290 ++ test/agent/test_cases.md | 2218 ++++++++++++ test/agent/test_cases_zh.md | 3136 +++++++++++++++++ {tests => test}/cli/test_claude_md_sync.py | 0 {tests => test}/cli/test_install_skills.py | 0 {tests => test}/cli/test_playbook_cli.py | 0 .../cli/test_sync_standards_cli.py | 0 .../integration/check_doc_links.sh | 0 test/templates/ci_validation_report.txt | 11 + test/templates/cpp_validation_report.txt | 11 + test/templates/project_templates_report.txt | 11 + test/templates/python_validation_report.txt | 11 + .../templates/validate_ci_templates.sh | 0 .../templates/validate_cpp_templates.sh | 0 .../templates/validate_project_templates.sh | 0 .../templates/validate_python_templates.sh | 0 {tests => test}/test_deployment_routes_e2e.py | 0 .../test_firstparty_skills_quality.py | 0 {tests => test}/test_format_md_action.py | 0 {tests => test}/test_gitattributes_modes.py | 0 .../test_gitea_workflow_bootstrap.py | 0 {tests => test}/test_main_loop_cli.py | 2 - {tests => test}/test_no_backup_flags.py | 0 {tests => test}/test_playbook_docs_index.py | 0 {tests => test}/test_script_line_endings.py | 0 {tests => test}/test_skills_readme.py | 0 .../test_sync_directory_actions.py | 0 .../test_sync_templates_placeholders.py | 27 +- .../test_thirdparty_skill_curation.py | 0 .../test_thirdparty_skills_pipeline.py | 0 {tests => test}/test_toml_edge_cases.py | 0 .../test_tsl_entrypoints_consistency.py | 123 +- 138 files changed, 7018 insertions(+), 1705 deletions(-) rename docs/tsl/reference/catalog/base/{03_date_basic.md => 02_date_basic.md} (91%) delete mode 100644 docs/tsl/reference/catalog/base/02_simple_conversion.md rename docs/tsl/reference/catalog/base/{04_datetime_parts.md => 03_datetime_parts.md} (100%) rename docs/tsl/reference/catalog/base/{05_datetime_boundaries.md => 04_datetime_boundaries.md} (100%) rename docs/tsl/reference/catalog/base/{06_datetime_relations.md => 05_datetime_relations.md} (100%) rename docs/tsl/reference/catalog/base/{07_range_predicates.md => 06_range_predicates.md} (100%) rename docs/tsl/reference/catalog/base/{08_range_getters.md => 07_range_getters.md} (100%) rename docs/tsl/reference/catalog/base/{09_range_span.md => 08_range_span.md} (100%) rename docs/tsl/reference/catalog/base/{10_time_shift.md => 09_time_shift.md} (100%) rename docs/tsl/reference/catalog/base/{11_compose_decompose_datetime.md => 10_compose_decompose_datetime.md} (100%) rename docs/tsl/reference/catalog/base/{12_datetime_recode.md => 11_datetime_recode.md} (100%) rename docs/tsl/reference/catalog/base/{13_datetime_format_conversion.md => 12_datetime_format_conversion.md} (100%) rename docs/tsl/reference/catalog/base/{14_wide_datetime_conversion.md => 13_wide_datetime_conversion.md} (100%) rename docs/tsl/reference/catalog/base/{15_string_common.md => 14_string_common.md} (100%) rename docs/tsl/reference/catalog/base/{16_string_predicates.md => 15_string_predicates.md} (100%) rename docs/tsl/reference/catalog/base/{17_string_replace_process.md => 16_string_replace_process.md} (100%) rename docs/tsl/reference/catalog/base/{18_string_array.md => 17_string_array_and_repeat.md} (69%) rename docs/tsl/reference/catalog/base/{21_byte.md => 18_byte.md} (100%) rename docs/tsl/reference/catalog/base/{22_phonetic.md => 19_phonetic.md} (100%) delete mode 100644 docs/tsl/reference/catalog/base/19_repeat.md delete mode 100644 docs/tsl/reference/catalog/base/20_multibyte_language.md rename docs/tsl/reference/catalog/base/{23_regex.md => 20_regex.md} (100%) rename docs/tsl/reference/catalog/base/{24_multilanguage.md => 21_multilanguage.md} (93%) rename docs/tsl/reference/catalog/base/{25_path_filename.md => 22_path_filename.md} (100%) rename docs/tsl/reference/catalog/base/{26_array_basic.md => 23_array_basic.md} (100%) rename docs/tsl/reference/catalog/base/{27_array_index_length.md => 24_array_index_length.md} (100%) rename docs/tsl/reference/catalog/base/{30_array_restructure.md => 25_array_sort_and_operations.md} (57%) rename docs/tsl/reference/catalog/base/{29_array_crud.md => 26_array_crud.md} (100%) delete mode 100644 docs/tsl/reference/catalog/base/28_array_sort.md delete mode 100644 docs/tsl/reference/catalog/datawarehouse/01_system_param_keys.md rename docs/tsl/reference/catalog/datawarehouse/{02_system_param_names.md => 01_system_param_names.md} (100%) rename docs/tsl/reference/catalog/datawarehouse/{03_multi_market.md => 02_multi_market.md} (100%) rename docs/tsl/reference/catalog/datawarehouse/{04_time.md => 03_time.md} (100%) rename docs/tsl/reference/catalog/datawarehouse/{05_predicates.md => 04_predicates.md} (90%) rename docs/tsl/reference/catalog/datawarehouse/{07_after_close_intraday_available.md => 05_intraday_and_after_close.md} (95%) delete mode 100644 docs/tsl/reference/catalog/datawarehouse/06_intraday.md rename docs/tsl/reference/catalog/datawarehouse/{08_time_series_stats.md => 06_time_series_stats.md} (100%) rename docs/tsl/reference/catalog/datawarehouse/{09_transaction_detail_data.md => 07_transaction_detail_data.md} (100%) rename docs/tsl/reference/catalog/datawarehouse/{10_transaction_detail_fields.md => 08_transaction_detail_fields.md} (100%) rename docs/tsl/reference/catalog/datawarehouse/{12_market_sector.md => 09_market_sector.md} (100%) rename docs/tsl/reference/catalog/datawarehouse/{13_quote_series.md => 10_quote_series.md} (100%) delete mode 100644 docs/tsl/reference/catalog/datawarehouse/11_query_polling.md rename docs/tsl/reference/catalog/datawarehouse/{14_reference_functions.md => 11_reference_functions.md} (100%) rename docs/tsl/reference/catalog/datawarehouse/{15_sys_param_access.md => 12_sys_param_access.md} (76%) rename docs/tsl/reference/catalog/datawarehouse/{16_reinstatement_types.md => 13_reinstatement.md} (53%) rename docs/tsl/reference/catalog/datawarehouse/{18_cycle.md => 14_cycle.md} (100%) rename docs/tsl/reference/catalog/datawarehouse/{19_financial.md => 15_financial.md} (100%) rename docs/tsl/reference/catalog/datawarehouse/{20_selection_and_fetch.md => 16_selection_and_fetch.md} (79%) delete mode 100644 docs/tsl/reference/catalog/datawarehouse/17_reinstatement_base_date.md rename docs/tsl/reference/catalog/datawarehouse/{21_wizard.md => 17_wizard.md} (100%) rename docs/tsl/reference/catalog/datawarehouse/{22_wizard_n_periods.md => 18_wizard_n_periods.md} (100%) rename docs/tsl/reference/catalog/datawarehouse/{23_wizard_n_days.md => 19_wizard_n_days.md} (100%) rename docs/tsl/reference/catalog/datawarehouse/{26_wizard_range.md => 20_wizard_range.md} (100%) rename docs/tsl/reference/catalog/datawarehouse/{27_wizard_intermediate.md => 21_wizard_intermediate.md} (66%) rename docs/tsl/reference/catalog/datawarehouse/{28_wizard_n_quarters.md => 22_wizard_n_quarters.md} (100%) rename docs/tsl/reference/catalog/datawarehouse/{29_wizard_today.md => 23_wizard_today.md} (100%) delete mode 100644 docs/tsl/reference/catalog/datawarehouse/24_wizard_n_days_intermediate.md rename docs/tsl/reference/catalog/datawarehouse/{30_wizard_today_intermediate.md => 24_wizard_today_intermediate.md} (100%) delete mode 100644 docs/tsl/reference/catalog/datawarehouse/25_wizard_legacy.md delete mode 100644 docs/tsl/reference/catalog/datawarehouse/31_condition_predicates.md rename docs/tsl/reference/catalog/resource/{08_process.md => 07_process.md} (100%) delete mode 100644 docs/tsl/reference/catalog/resource/07_wide_byte.md rename docs/tsl/reference/catalog/resource/{09_local_resource.md => 08_local_resource.md} (100%) delete mode 100644 docs/tsl/reference/catalog/system/03_copy.md rename docs/tsl/reference/catalog/system/{04_global_cache.md => 03_global_cache.md} (100%) rename docs/tsl/reference/catalog/system/{05_random.md => 04_random.md} (100%) rename docs/tsl/reference/catalog/system/{07_expression.md => 05_expression.md} (100%) delete mode 100644 docs/tsl/reference/catalog/system/06_conditional.md rename docs/tsl/reference/catalog/system/{09_tsl_lib_path.md => 06_tsl_lib_path.md} (100%) rename docs/tsl/reference/catalog/system/{10_error_assertion.md => 07_error_and_assertion.md} (59%) delete mode 100644 docs/tsl/reference/catalog/system/08_profiler.md create mode 100644 docs/tsl/syntax/00_agent_index.json delete mode 100644 templates/prompts/meta/prompt-generator.template.md rename {tests => test}/README.md (100%) create mode 100644 test/agent/README.md create mode 100644 test/agent/test_cases.md create mode 100644 test/agent/test_cases_zh.md rename {tests => test}/cli/test_claude_md_sync.py (100%) rename {tests => test}/cli/test_install_skills.py (100%) rename {tests => test}/cli/test_playbook_cli.py (100%) rename {tests => test}/cli/test_sync_standards_cli.py (100%) rename {tests => test}/integration/check_doc_links.sh (100%) create mode 100644 test/templates/ci_validation_report.txt create mode 100644 test/templates/cpp_validation_report.txt create mode 100644 test/templates/project_templates_report.txt create mode 100644 test/templates/python_validation_report.txt rename {tests => test}/templates/validate_ci_templates.sh (100%) rename {tests => test}/templates/validate_cpp_templates.sh (100%) rename {tests => test}/templates/validate_project_templates.sh (100%) rename {tests => test}/templates/validate_python_templates.sh (100%) rename {tests => test}/test_deployment_routes_e2e.py (100%) rename {tests => test}/test_firstparty_skills_quality.py (100%) rename {tests => test}/test_format_md_action.py (100%) rename {tests => test}/test_gitattributes_modes.py (100%) rename {tests => test}/test_gitea_workflow_bootstrap.py (100%) rename {tests => test}/test_main_loop_cli.py (99%) rename {tests => test}/test_no_backup_flags.py (100%) rename {tests => test}/test_playbook_docs_index.py (100%) rename {tests => test}/test_script_line_endings.py (100%) rename {tests => test}/test_skills_readme.py (100%) rename {tests => test}/test_sync_directory_actions.py (100%) rename {tests => test}/test_sync_templates_placeholders.py (93%) rename {tests => test}/test_thirdparty_skill_curation.py (100%) rename {tests => test}/test_thirdparty_skills_pipeline.py (100%) rename {tests => test}/test_toml_edge_cases.py (100%) rename {tests => test}/test_tsl_entrypoints_consistency.py (93%) diff --git a/.gitea/workflows/standards-check.yml b/.gitea/workflows/standards-check.yml index dd6928ce..8384d773 100644 --- a/.gitea/workflows/standards-check.yml +++ b/.gitea/workflows/standards-check.yml @@ -27,7 +27,7 @@ jobs: set -euo pipefail echo "========================================" - echo "📥 准备仓库到 WORKSPACE_DIR" + echo "📦 准备仓库到 WORKSPACE_DIR" echo "========================================" REPO_NAME="${{ github.event.repository.name }}" @@ -60,10 +60,14 @@ jobs: git config --global --add safe.directory "$REPO_DIR" echo "REPO_DIR=$REPO_DIR" >> "$GITHUB_ENV" - - name: 🧪 Lint commit message / PR title + echo "✅ 仓库准备完成" + + - name: 🔍 Lint commit message / PR title run: | cd "$REPO_DIR" + echo "🔍 检查 commit message 和 PR title 规范..." python3 .gitea/ci/commit_message_lint.py + echo "✅ Lint 检查通过" - name: 🧹 清理临时仓库 if: always() diff --git a/.gitea/workflows/test.yml b/.gitea/workflows/test.yml index 970ba2cf..47dbbe05 100644 --- a/.gitea/workflows/test.yml +++ b/.gitea/workflows/test.yml @@ -35,7 +35,7 @@ jobs: set -euo pipefail echo "========================================" - echo "📥 准备仓库到 WORKSPACE_DIR" + echo "📦 准备仓库到 WORKSPACE_DIR" echo "========================================" REPO_NAME="${{ github.event.repository.name }}" @@ -69,11 +69,12 @@ jobs: git config --global --add safe.directory "$REPO_DIR" echo "REPO_DIR=$REPO_DIR" >> "$GITHUB_ENV" + echo "✅ 仓库准备完成" - name: 🔧 安装测试依赖 run: | echo "========================================" - echo "🔧 安装测试依赖" + echo "📦 安装测试依赖" echo "========================================" apt-get update @@ -83,7 +84,8 @@ jobs: python3 -m pip install yamllint tomli echo "" - echo "✓ Python 版本: $(python3 --version)" + echo "✅ Python 版本: $(python3 --version)" + echo "✅ 依赖安装完成" echo "========================================" - name: 🧪 运行全量测试并生成报告 @@ -92,27 +94,31 @@ jobs: set -euo pipefail echo "========================================" - echo "🧪 Python 测试" + echo "🐍 Python 测试" echo "========================================" cd "$REPO_DIR" - echo "覆盖：CLI、subtree/snapshot 部署路线、模板同步、文档一致性" - python3 -m unittest discover -s tests -p "test_*.py" -v + echo "📋 覆盖：CLI、subtree/snapshot 部署路线、模板同步、文档一致性" + python3 -m unittest discover -s test -p "test_*.py" -v + echo "✅ Python 测试通过" echo "========================================" - echo "📄 模板验证测试" + echo "📝 模板验证测试" echo "========================================" sh tests/templates/validate_python_templates.sh sh tests/templates/validate_cpp_templates.sh sh tests/templates/validate_ci_templates.sh sh tests/templates/validate_project_templates.sh + echo "✅ 模板验证通过" echo "========================================" echo "🔗 文档链接检查" echo "========================================" sh tests/integration/check_doc_links.sh + echo "✅ 文档链接检查通过" + echo "🎉 所有测试完成" - name: 🧹 清理临时仓库 if: always() diff --git a/.gitea/workflows/update-thirdparty-skills.yml b/.gitea/workflows/update-thirdparty-skills.yml index 378e5b6c..ab0b2364 100644 --- a/.gitea/workflows/update-thirdparty-skills.yml +++ b/.gitea/workflows/update-thirdparty-skills.yml @@ -29,7 +29,7 @@ jobs: set -euo pipefail echo "========================================" - echo "🧰 Prepare repo in WORKSPACE_DIR" + echo "📦 Prepare repo in WORKSPACE_DIR" echo "========================================" REPO_NAME="${{ github.event.repository.name }}" @@ -49,6 +49,7 @@ jobs: git config --global --add safe.directory "$REPO_DIR" echo "REPO_DIR=$REPO_DIR" >> "$GITHUB_ENV" + echo "✅ Repo prepared" - name: ♻️ Update thirdparty and sync main shell: bash @@ -81,7 +82,7 @@ jobs: fi echo "========================================" - echo "🚀 Sync skills into main" + echo "🔄 Sync skills into main" echo "========================================" git fetch origin main @@ -92,7 +93,7 @@ jobs: MANIFEST_PATH="$MANIFEST_PATH" \ bash .gitea/ci/sync_thirdparty_skills.sh - echo "🎉 Update and sync finished." + echo "✅ Update and sync finished." - name: 🧹 Clean temporary repo if: always() diff --git a/.gitignore b/.gitignore index 6689d177..7b75b9f2 100644 --- a/.gitignore +++ b/.gitignore @@ -24,6 +24,9 @@ reports/ tmp/ docs/superpowers/ +# Agent 测试结果 +test/agent/result/ + scripts/__pycache__ -tests/__pycache__ -tests/cli/__pycache__ +test/__pycache__ +test/cli/__pycache__ diff --git a/README.md b/README.md index 73532951..be280594 100644 --- a/README.md +++ b/README.md @@ -9,17 +9,6 @@ Playbook：工程规范与代理规则合集，当前覆盖： - JavaScript（`.js`/`.mjs`/`.cjs`） - Markdown（代码格式化） -## 原则 - -1. **可读性优先**：读代码的时间远大于写代码 -2. **一致性优先**：同一仓库内保持一致比追求"最优风格"更重要 -3. **遵从既有代码**：修改/扩展现有代码时优先沿用其局部风格 - -## 适用范围 - -- 本指南适用于所有 TSL/C++/Python/TypeScript/JavaScript/Markdown 相关仓库与脚本 -- 当现有代码与本指南冲突时，**以保持局部一致性为优先**，逐步迁移 - ## docs/（开发规范） `docs/` 目录是给开发者阅读的工程规范，约束代码写法、命名与提交信息。 @@ -77,36 +66,7 @@ project_name = "MyProject" - **CLAUDE.md**：自动检测（根目录 → `.claude/`），不存在则创建；注入 `@AGENTS.md` / `@AGENT_RULES.md` - **force**：默认 false，已存在则跳过；设为 true 时强制覆盖（会先备份） -### 工作流留痕 helper - -如果项目已经部署了这套模板，并使用 `superpowers` 工作流： - -```bash -# spec 写完后 -python /scripts/playbook.py \ - -record-spec docs/superpowers/specs/-design.md \ - -progress memory-bank/progress.md - -# plan 写完后 -python /scripts/playbook.py \ - -record-plan docs/superpowers/plans/.md \ - -progress memory-bank/progress.md -``` - -这两个 helper 只负责把 `workflow-state` 写入 -`memory-bank/progress.md`。 -spec/plan 产出阶段不单独提交；最终随对应 Plan 的交付变更统一归档。 -真正执行 Plan 仍然走 `main_loop.py claim/finish`。 - -完整主链只在 `templates/AGENT_RULES.template.md` 定义，这里不重复展开。 -如果项目采用 `superpowers`： - -- 设计产物落到 `docs/superpowers/specs/` -- 计划产物落到 `docs/superpowers/plans/` -- 状态留痕通过 `playbook.py -record-spec/-record-plan` 与 - `main_loop.py claim/finish` 维护 - -详见：`templates/README.md` +更多说明详见 [templates/README.md](templates/README.md)。 ## rulesets/（规则集模板库 - 三层架构） @@ -124,7 +84,7 @@ spec/plan 产出阶段不单独提交；最终随对应 Plan 的交付变更统 ```txt Layer 1: rulesets/ (≤50 行/语言，模板源) - ├─ 核心约束与安全红线 + ├─ 语言特有的核心约束 └─ 指向 Skills 和 docs Layer 2: skills/ (按需加载，$skill-name 触发) @@ -140,7 +100,7 @@ Layer 3: docs/ (权威静态文档) | 层级 | 加载方式 | 内容 | 作用 | | ------- | ------------------------------ | ------------------------------ | -------------------------- | -| Layer 1 | 自动，始终在上下文 | 硬约束与安全红线 | 快速判断能做/不能做 | +| Layer 1 | 自动，始终在上下文 | 语言特有的核心约束 | 快速判断能做/不能做 | | Layer 2 | `$` 触发或代理判定 | 操作指南、最佳实践、工作流 | 指导具体怎么做 | | Layer 3 | 按需读取特定章节 | 完整语言手册、代码风格、工具链 | 最终权威（冲突时以此为准） | @@ -159,7 +119,7 @@ Layer 3: docs/ (权威静态文档) **.agents/（Layer 1）修改规则**： -- 可做：增加安全漏洞类型、更新核心约定、添加硬性约束 +- 可做：更新核心约定、添加语言特有的硬性约束(命名/语法/工具链) - 不可做：添加推荐型最佳实践（→ skill）、详细语法解释（→ skill/docs）、超过 50 行（→ 拆分） **Skills（Layer 2）创建规则**： @@ -168,20 +128,9 @@ Layer 3: docs/ (权威静态文档) ## SKILLS（Codex CLI / Claude Code） -本仓库内置一组 AI agent skills（见 `skills/`），支持 Codex CLI 和 Claude Code，用于按需加载的工作流与知识库。 +本仓库内置 AI agent skills，支持 Codex CLI 和 Claude Code，用于按需加载的工作流与知识库。 -TSL 相关问题直接查阅 `rulesets/tsl/index.md` 与 `docs/tsl/`。 - -**通用 Skills**： - -- `$commit-message`：提交信息规范 -- `$gitea-fix-ci`：诊断 Gitea Actions / PR checks 失败并按批准计划修复 -- `$style-cleanup`：整理代码风格 -- 更多见 `SKILLS.md` - -**安装与使用**：详见 `SKILLS.md` - -如果你通过 `[install_skills]` 更新已经安装过的 skill，默认会先把旧目录备份为 `*.bak.`；如果你明确希望“删除旧版本后直接重装”，可在 `playbook.toml` 的 `[install_skills]` 下设置 `no_backup = true`。 +安装与使用详见 [SKILLS.md](SKILLS.md)。 ## 在其他项目中使用本 Playbook @@ -195,46 +144,6 @@ TSL 相关问题直接查阅 `rulesets/tsl/index.md` 与 `docs/tsl/`。 | 不想把 Playbook 以 subtree 嵌进仓库，但仍要把标准部署到项目内 | 方式二：外部 clone 后执行部署 | Playbook 仓库与业务仓库解耦，部署根目录可配置 | | **不确定？** | **方式一：`git subtree`（推荐）** | 项目内可见、版本可追溯、使用路径最稳定 | ---- - -### TL;DR - 30 秒快速开始 - -先区分三个路径概念： - -- `project_root`：目标项目根目录。 -- `playbook_root`：相对于 `project_root` 的项目内 Playbook 根目录。 -- `install_mode`：`subtree` 表示 Playbook 已由 git subtree 放在项目内；`snapshot` 表示从外部 clone 安装裁剪快照。 -- 外部 clone 出来的 Playbook 路径（如 `/opt/playbook`）：只是执行安装脚本的位置，不是项目内 Playbook 根目录。 - -以 TSL 为例，Playbook 在项目内的默认根是 `docs/standards/playbook`；如果你把 `playbook_root` 改成 `custom/playbook`，则快照会落到 `/custom/playbook`，文档和脚本入口也会跟着变成 `custom/playbook/docs/...`、`custom/playbook/scripts/...`。 - -#### 方式一：`git subtree` - -```bash -# 1. 引入标准快照 -git subtree add --prefix docs/standards/playbook https://git.mytsl.cn/csh/playbook.git main --squash - -# 2. 在项目根创建配置（示例见 docs/standards/playbook/playbook.toml.example） -cat <<'EOF' > playbook.toml -[playbook] -project_root = "." -playbook_root = "docs/standards/playbook" -install_mode = "subtree" - -[sync_standards] -langs = ["tsl"] -EOF - -# 3. 执行统一入口 -python docs/standards/playbook/scripts/playbook.py -config playbook.toml - -# 4. 提交 -git add . -git commit -m ":package: deps(playbook): add tsl standards" -``` - ---- - ### 方式一：git subtree 同步（推荐） 1. 在目标项目中首次引入： @@ -271,7 +180,7 @@ git commit -m ":package: deps(playbook): add tsl standards" python docs/standards/playbook/scripts/playbook.py -config playbook.toml ``` -配置参数说明见 `docs/standards/playbook/playbook.toml.example`。 +配置参数说明见 [playbook.toml.example](playbook.toml.example)。 --- @@ -285,11 +194,7 @@ git commit -m ":package: deps(playbook): add tsl standards" git clone https://git.mytsl.cn/csh/playbook.git /opt/playbook ``` -2. 在目标项目根创建 `playbook.toml`，并用 `playbook_root` 指定项目内的 Playbook 根。例如： - - `project_root` 写目标项目根目录。 - - `playbook_root` 写目标项目内的相对路径。 - - `install_mode = "snapshot"` 表示由外部 clone 安装项目内快照。 - - 不要把外部 clone 的路径（如 `/opt/playbook`）写进 `playbook_root`；那只是你执行脚本的位置。 +2. 在目标项目根创建 `playbook.toml`： ```toml [playbook] @@ -312,12 +217,7 @@ git commit -m ":package: deps(playbook): add tsl standards" python /opt/playbook/scripts/playbook.py -config playbook.toml ``` -说明： - -- `install_mode = "snapshot"` 会先把 Playbook 裁剪快照安装到目标项目的 `playbook_root`，再执行后续同步动作。 -- `playbook_root` 永远表示目标项目内的 Playbook 根；它不是外部 clone 出来的 Playbook 仓库路径。 -- 外部 clone 场景下必须显式填写 `playbook_root`；脚本不会替你补默认项目内根目录。 -- 如果 `playbook_root = "custom/playbook"`，部署后的项目内入口会是 `custom/playbook/scripts/playbook.py`、`custom/playbook/docs/index.md`。 +**说明**：`playbook_root` 表示项目内的部署目录，不是外部 clone 的路径。 --- @@ -336,7 +236,7 @@ git commit -m ":package: deps(playbook): add tsl standards" 本仓库提供多套代理规则集（同步后位于目标项目的 `.agents/tsl/` / `.agents/cpp/` / `.agents/python/` / `.agents/typescript/` / `.agents/markdown/`）： -- 各规则集都包含核心约定与安全红线 +- 各规则集都包含语言特有的核心约定 - 并在 `index.md` 中叠加语言级"硬约束"（TSL/TSF 语法限制、C++23/Modules、Python 风格、TypeScript 类型约束、Markdown 代码格式化等） **多语言项目推荐结构**（示例：TSL + C++ + Python + TypeScript + Markdown）： @@ -366,5 +266,4 @@ git commit -m ":package: deps(playbook): add tsl standards" **规则优先级建议**： - 同一项目内多个规则集并行放在 `.agents//`，不要互相覆盖 -- 若某个子目录需要更具体规则（模块/子系统差异），在更靠近代码的目录放置更具体规则（例如 - `src/foo/.agents/`），并以"离代码更近者优先"为准 +- 若某个子目录需要更具体规则（模块/子系统差异），在更靠近代码的目录放置更具体规则（例如 `src/foo/.agents/`），并以"离代码更近者优先"为准 diff --git a/SKILLS.md b/SKILLS.md index 8a6c3e01..47d6c6c6 100644 --- a/SKILLS.md +++ b/SKILLS.md @@ -1,7 +1,6 @@ # SKILLS -本文件定义：如何在仓库中落地与维护 **AI agent skills**， -并给出与本 Playbook（`docs/` + `rulesets/`）配套的技能编写建议与内置技能清单。 +本文档说明如何安装、启用和使用 AI agent skills。 支持的平台： @@ -10,11 +9,11 @@ | Codex CLI | `~/.agents/skills/` | | Claude Code | `~/.claude/skills/` | -> 提示：本仓库将 skills 以可分发的形式放在 `skills/`，并提供脚本一键安装到对应平台目录。 - --- -## 1. 启用 skills（必做） +## 用户指南 + +### 1. 启用 skills（必做） **Codex CLI** — 在 `~/.codex/config.toml` 中启用： @@ -29,39 +28,11 @@ skills = true ```json { - "skills": true + “skills”: true } ``` ---- - -## 2. 本仓库的 skills 目录结构 - -本 Playbook 以“可分发、可安装”的方式提供 skills： - -```txt -skills/ - / # 本仓库自维护 - SKILL.md - references/ # 可选：拆分参考文档 - templates/ # 可选：模板 - scripts/ # 可选：脚本/命令封装 - thirdparty/ # 第三方同步（不可手动修改） - / - SKILL.md - .sources/ # 第三方来源清单 -``` - -最终安装到本机后，对应路径为： - -| 平台 | 路径 | -| ----------- | ---------------------------------------- | -| Codex CLI | `~/.agents/skills//SKILL.md` | -| Claude Code | `~/.claude/skills//SKILL.md` | - ---- - -## 3. 安装到本机（推荐） +### 2. 安装到本机 使用统一入口 `playbook.py` 安装 skills，通过 `agents_home` 指定目标平台目录： @@ -115,31 +86,66 @@ python /scripts/playbook.py -config playbook.toml 其中 `` 默认为 `docs/standards/playbook`。 ---- - -## 4. `SKILL.md` 最小规范 - -- 文件名必须是 `SKILL.md` -- 必须包含 YAML frontmatter（用 `---` 包裹），且至少包含： - - `name`：非空，≤100 字符，建议 kebab-case 且与目录名一致 - - `description`：非空，≤500 字符（写“用户会怎么说”的触发词；避免换行） -- frontmatter 之外的正文可以是任意 Markdown（用于工作流说明/决策树/命令/模板索引） - ---- - -## 5. 使用方式 +### 3. 使用方式 - 在对话中通过 `$` 直接点名触发（例如：`$style-cleanup`） - Codex TUI：可用 `/skills` 浏览与插入 - Claude Code：通过 `/skills` 命令或直接在对话中触发 +### 4. 可用 Skills 清单 + +完整清单（含作用说明、典型场景）见 [skills/README.md](skills/README.md)。 + +### 5. 运行时排障 + +- **不触发**： + - Codex：确认已启用 `[features] skills = true`，重启 `codex` + - Claude Code：确认 skills 已启用，重启 Claude Code + - 确认 skill 已安装到对应平台目录 +- **触发错**：减少不同 skill 的 `description` 关键词重叠；让触发词更具体（语言/工具/目录名/流程名） +- **启动报错**：通常是 YAML frontmatter 不合法或字段超长；修复后重启即可 + --- -## 6. 设计原则（写给维护者） +## 开发者指南 -把 skill 当作“可检索的工作流模块”，而不是长篇教程： +### 目录结构 -1. **边界清晰**：只写“仓库/组织特定”的流程、约束与验收标准；避免通用编程常识。 +本 Playbook 以"可分发、可安装"的方式提供 skills： + +```txt +skills/ + / # 本仓库自维护 + SKILL.md + references/ # 可选：拆分参考文档 + templates/ # 可选：模板 + scripts/ # 可选：脚本/命令封装 + thirdparty/ # 第三方同步（不可手动修改） + / + SKILL.md + .sources/ # 第三方来源清单 +``` + +最终安装到本机后，对应路径为： + +| 平台 | 路径 | +| ----------- | ---------------------------------------- | +| Codex CLI | `~/.agents/skills//SKILL.md` | +| Claude Code | `~/.claude/skills//SKILL.md` | + +### `SKILL.md` 最小规范 + +- 文件名必须是 `SKILL.md` +- 必须包含 YAML frontmatter（用 `---` 包裹），且至少包含： + - `name`：非空，≤100 字符，建议 kebab-case 且与目录名一致 + - `description`：非空，≤500 字符（写”用户会怎么说”的触发词；避免换行） +- frontmatter 之外的正文可以是任意 Markdown（用于工作流说明/决策树/命令/模板索引） + +### 设计原则 + +把 skill 当作”可检索的工作流模块”，而不是长篇教程： + +1. **边界清晰**：只写”仓库/组织特定”的流程、约束与验收标准；避免通用编程常识。 2. **description 负责检索**：把团队常用说法（中英文同义词）写进 `description`，降低漏触发概率。 3. **SOP 化**：建议包含 Inputs → Procedure → Output Contract → Success Criteria @@ -148,9 +154,7 @@ python /scripts/playbook.py -config playbook.toml `references/`，引用深度 ≤ 1。 5. **高风险低自由度**：破坏性操作（删数据/重写历史/生产变更）默认先停下确认，并给回滚方案。 ---- - -## 7. Playbook 权威来源（可在 skill 中引用） +### Playbook 权威来源（可在 skill 中引用） - 提交信息：`docs/common/commit_message.md` - TSL：`docs/tsl/code_style.md`、`docs/tsl/naming.md`、`docs/tsl/toolchain.md` @@ -160,55 +164,21 @@ python /scripts/playbook.py -config playbook.toml 若你的项目把本 Playbook 部署到项目内，文档根路径为 `/docs/...`；其中 `` 默认为 `docs/standards/playbook`，也可以按项目配置改成 `custom/playbook` 等自定义目录。 ---- +### 第三方 Skills 同步机制 -## 8. 本 Playbook 原生 skills +本仓库通过 `thirdparty/skill` 分支同步第三方 skills。 -位于 `skills/`（Playbook 自维护部分），当前共 3 个。 -第三方 skills 来源见第 9 节。 +**来源登记**： -### 语言特定 Skills +- `skills/thirdparty/.sources/`：来源清单目录（`*.list` 文件） +- `skills/thirdparty/thirdparty-skills.yml`：统一配置文件 -当前仓库不再内置语言特定 skill；TSL 相关问题请直接查阅 `rulesets/tsl/index.md` 与 `docs/tsl/`。 +**同步流程**： -### 通用工作流 Skills - -- `commit-message`：基于 staged diff 自动建议提交信息（`:emoji: type(scope): subject`） -- `gitea-fix-ci`：诊断 Gitea Actions / PR checks 失败，先提取日志证据并形成修复计划，再按批准范围改代码 -- `style-cleanup`：整理代码风格（优先使用仓库既有 formatter/lint 工具链） +1. 上游快照保存在 `thirdparty/skill` 分支 +2. 自动同步后，落到仓库内 `skills/thirdparty//` +3. 运行 `[install_skills]` 时，复制到目标平台 skills 目录（`~/.agents/skills/` 或 `~/.claude/skills/`） --- -## 9. Third-party Skills - -来源：`skills/thirdparty/.sources/`（第三方来源清单目录）。 - -- `superpowers.list` -- `ui-ux-pro-max.list` -- `andrej-karpathy-skills.list` -- `brooks-lint.list` -- `codebase-recon.list` -- `codebase-migrate.list` -- `uncle-bob-craft.list` - -部署链路： - -- `thirdparty/skill` 分支保存各上游快照，例如 `andrej-karpathy-skills/`、`awesome-codex-skills/`、`antigravity-awesome-skills/` -- 自动同步后，选中的下游 skill 会落到仓库内 `skills/thirdparty//` -- 运行 `[install_skills]` 时，再复制到目标平台 skills 目录（`~/.agents/skills/` 或 `~/.claude/skills/`） -- 该 skill 本身不依赖 Playbook 文档路径重写，也不需要像 `ui-ux-pro-max` 那样额外渲染 - ---- - -## 10. 运行时排障 - -- 不触发： - - Codex：确认已启用 `[features] skills = true`，重启 `codex` - - Claude Code：确认 skills 已启用，重启 Claude Code - - 确认 skill 已安装到对应平台目录（`~/.agents/skills/` 或 `~/.claude/skills/`） -- 触发错：减少不同 skill 的 `description` 关键词重叠；让触发词更具体（语言/工具/目录名/流程名）。 -- 启动报错：通常是 YAML frontmatter 不合法或字段超长；修复后重启即可。 - ---- - -**最后更新**：2026-01-26 +**最后更新**：2026-06-17 diff --git a/docs/tsl/code_style.md b/docs/tsl/code_style.md index 9d5e23a6..fb6a08d1 100644 --- a/docs/tsl/code_style.md +++ b/docs/tsl/code_style.md @@ -4,7 +4,7 @@ 是否可直接用于生成代码：仅部分 是否含可直接照写示例：否 是否含不可照写反例：否 -遇到不确定时：[naming.md](naming.md)、[syntax/index.md](syntax/index.md)、[toolchain.md](toolchain.md) +遇到不确定时：风格/命名看 [naming.md](naming.md)；语法事实看 [syntax/index.md](syntax/index.md)；验证命令或自动化入口只看项目脚本、CI，或目标项目已真实填写且没有 `<...>` 占位符的 [toolchain.md](toolchain.md) 本页记录本仓库代码风格偏好，不代表 TSL 语法事实。 @@ -22,20 +22,19 @@ ### 1.1 单一职责 - 一个文件只做一件事；职责明确。 -- `.tsl` 作为可执行脚本：语句区在前并按顺序执行；需要本文件函数/类时，声明区放在语句区之后。 -- `.tsf` 作为模块/函数扩展文件：可复用逻辑下沉到 `.tsf`，部署到解释器 `funcext` 后供脚本调用。 +- 文件模型和顶层声明规则以 `docs/tsl/syntax/02_core_model.md` 为准；本页只规定组织偏好。 +- 可复用逻辑优先集中到可复用声明文件；入口/编排层只保留必要流程。 - 当一个顶层声明同时承担“协议适配 + 业务计算 + I/O/环境依赖 + 临时代码”时，优先拆分边界：核心纯逻辑 → 工具函数 → 边界适配（I/O）。 -### 1.2 文件名与顶层声明（硬约束） +### 1.2 文件名与顶层声明 -- TSL 语法要求（仅 `.tsf`）：每个 `.tsf` - 文件只能有一个顶层声明，且文件基名必须与顶层声明同名。 -- `.tsl` 允许直接写语句，不要求顶层声明；文件名不强制，但建议清晰可检索。 -- `.tsl` 中如果同时需要脚本语句和函数/类声明，先写语句区，再写声明区；不要在声明区后继续追加脚本语句。 +- 文件模型和顶层声明规则以 `docs/tsl/syntax/02_core_model.md` 为准；文件和实体如何命名见 + `docs/tsl/naming.md`。 +- 文件名不强制表达完整职责，但应清晰可检索。 - 推荐文件名使用 `PascalCase` 以提升检索与协作一致性；扩展名按类型使用 `.tsl`/`.tsf`（两者都属于 TSL 源文件，风格规则一致）。 -- 详细约束与命名细则见 `docs/tsl/naming.md`。 +- 重命名时同步检查引用、调用点、项目配置和文档链接。 ### 1.3 依赖与分层 @@ -92,6 +91,7 @@ end - 多语句分支使用 `begin/end` 包裹：在 `then/else` 后换行写 `begin`，`end` 单独成行。 - `else/elseif` 等分支关键字另起一行，与上一块的 `end` 对齐。 +- 控制流块（`if`/`while`/`for`/`case`/`try` 等）的 `end` 后不加分号；顶层声明（函数/过程/类/`unit`）的 `end` 后加分号（这是语法要求，见 `syntax/05_functions_and_calls.md` 和 `syntax/09_units_and_scope.md`）。 - 单语句分支可省略 `begin/end`（保持清晰优先；一旦分支变复杂就回退到块结构）： 代码块身份：配置片段 / 概念骨架 @@ -195,8 +195,8 @@ count := count + 1; ## 4. 代码实践（Best Practices） -> 本节偏“实践建议”（should），用于提升可读性/可测试性；若目标项目有更严格的约束与检查命令，以项目落地的工具链为准（参考 -> `docs/tsl/toolchain.md`）。如果项目对自动化或 AI 代理有额外要求，应把约束直接写进仓库内可见的检查脚本、CI 配置或项目文档，而不是依赖隐藏规范。 +> 本节偏“实践建议”（should），用于提升可读性/可测试性；若目标项目有更严格的约束与检查命令，以项目脚本、CI 配置，或已填写且没有 `<...>` 占位符的 +> `docs/tsl/toolchain.md` 为准。如果项目对自动化或 AI 代理有额外要求，应把约束直接写进仓库内可见的检查脚本、CI 配置或项目文档，而不是依赖隐藏规范。 ### 4.1 变量与常量 diff --git a/docs/tsl/index.md b/docs/tsl/index.md index b4e83520..9d78627c 100644 --- a/docs/tsl/index.md +++ b/docs/tsl/index.md @@ -1,83 +1,42 @@ # TSL 文档入口 -文档类型：检索页 +文档类型：跨层路由页 是否可直接用于生成代码：否 是否含可直接照写示例：否 是否含不可照写反例：否 -遇到不确定时：先按本文“任务路由”分层；语法问题看 [syntax/index.md](syntax/index.md)，函数库查询看 [reference/index.md](reference/index.md)，模块 / 集成看 [modules/index.md](modules/index.md)，项目执行问题回项目自身文档、`scripts/*` 入口脚本和 CI 配置 +遇到不确定时：先按“按任务跳转”分层；语法问题看 [syntax/index.md](syntax/index.md)，函数库查询看 [reference/index.md](reference/index.md)，模块 / 集成看 [modules/index.md](modules/index.md)，项目执行问题回项目自身文档、`scripts/*` 入口脚本和 CI 配置 -本入口只负责一件事：让智能体先判断主问题属于哪一层，再进入最相关的单个入口页。本套 TSL 文档面向智能体决策，不按人类教程组织；回答和生成代码时必须按流程读，不要凭语言相似性补全。 +本页只决定第一跳。不要在这里生成代码，不要通读全部 TSL 文档，不要用相似语言补全 TSL 事实。 -## 起手规则 +## 按任务跳转 -1. 先判断主问题层：语法、函数库、模块 / 集成，还是项目执行。 -2. 只进入命中的单个入口页；不要同时展开语法、业务、函数库、模块和工具链。 -3. 如果要生成或修改 TSL 代码，先做文件模型初判；详细规则见 [syntax/02_core_model.md](syntax/02_core_model.md)： - - 用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据。 - - 用户未给后缀时，按交付目标判断：入口流程、脚本任务或一次性执行逻辑对应 `.tsl`；可复用函数、过程、类、模块或扩展对应 `.tsf`。 - - 仍不明确时先向用户确认，不要靠相似语言补全。 -4. 写代码前找 `代码块身份：可直接照写示例`；遇到 `反例 / 不可照写`、输出片段或概念骨架必须避开。 -5. 语法细节统一进入 [syntax/index.md](syntax/index.md) 后再分流；本页只保留跨层路由需要的最小提醒。 -6. 本手册没有结论时，不要发明语法；改为向用户确认、记录文档缺口，或交由维护者补充文档结论。 +| 任务信号 | 入口 | 阻断条件 | +| ------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------ | +| 写最短可运行骨架、核对语言核心事实 | [syntax/01_quickstart.md](syntax/01_quickstart.md) | `.tsl` / `.tsf` 文件模型不明 | +| 判断语法能不能写、查语言写法 | [syntax/index.md](syntax/index.md) | 没有命中具体语法专题 | +| 核对高频误写、反例、负向边界 | [syntax/11_pitfalls.md](syntax/11_pitfalls.md) | 反例没有指向正确专题 | +| 查行情、财务、板块、选股等金融函数 | [reference/catalog/datawarehouse.md](reference/catalog/datawarehouse.md) | 没有命中带参数表的函数事实条目 | +| 查通用函数库函数名、参数、返回值 | [reference/index.md](reference/index.md) | catalog 没有正式函数条目 | +| 用 Python 调 TSL、调用服务器函数、批量或异步取数 | [modules/pytsl_api.md](modules/pytsl_api.md) | 真实账号、服务地址、业务字段来自项目上下文 | +| 写回测框架、组合回测、读取回测结果 | [modules/tsbacktesting.md](modules/tsbacktesting.md) | 策略信号、证券池、资金参数缺失 | +| 看模块、集成、互操作入口 | [modules/index.md](modules/index.md) | 模块 API 与项目执行边界不清 | +| 确认账户、真实接口、部署、脚本入口、环境变量或 CI | 项目自身文档、`scripts/*` 入口脚本、CI 配置 | 只有通用 TSL 文档，没有项目事实 | -## 元数据与证据标签 +项目执行事实条件：只有目标项目已真实填写且没有 `<...>` 占位符的 [toolchain.md](toolchain.md) 才可作为执行依据。 -- 页头里的 `是否可直接用于生成代码` 只做页面级粗判断；如果页内已经给出 `代码块身份`，一律以块级标签为准。 -- `是否可直接用于生成代码` 有三种值：`是`、`否`、`仅部分`；其中 `仅部分` 表示页内既有可直接参考的块，也有依赖多文件、查找路径或运行时环境的块，必须继续看块级标签。 -- `是否含可直接照写示例` 只统计可直接照写的正向代码示例。 -- `是否含不可照写反例` 只统计不可照写的负向例子。 -- `代码块身份` 只使用固定词表：`可直接照写示例`、`输出片段`、`反例 / 不可照写`、`配置片段 / 概念骨架`。 -- 如果还需要补充用途、限制或复用建议，单独写 `代码块说明`，不要把说明文字继续拼进 `代码块身份`。 -- 如果页头里的 `遇到不确定时` 列出多个目标，普通专题页默认第一项是优先入口；总入口页例外，必须先按任务路由分层。 +## 证据规则 -## 语法事实使用规则 +- 页头元数据只做页面级粗判断；生成代码时以块级 `代码块身份` 为准。 +- `可直接照写示例` 用于代码外形、语句顺序和块级结构。 +- `输出片段` 只表示结果或错误形态。 +- `反例 / 不可照写` 只用于避开错法，不反推新语法。 +- `配置片段 / 概念骨架` 只表示结构提示，不代表可运行源码。 +- 语法页不承载执行环境、账户体系、真实接口或验证命令。 -- TSL 语法页面面向智能体生成代码；写成语法事实的内容就是生成依据，不再要求智能体自行证明。 -- `可直接照写示例` 用于参考代码外形、语句顺序和块级结构。 -- `输出片段` 只用于理解返回结果或错误形态，不作为代码照写。 -- `反例 / 不可照写` 只用于避开对应写法，不反向推导新的语法。 -- `配置片段 / 概念骨架` 只说明结构或配置位置，不代表可直接运行。 -- 文档没有覆盖的写法不能生成；应向用户确认、记录文档缺口，或回到项目实际代码寻找证据。 -- 执行环境细节不写进语法页；项目执行信息不能混入通用 TSL 事实。 +## 停止条件 -## 任务路由 - -| 任务 | 先读哪里 | -| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -| 我要系统入门 TSL | [syntax/index.md](syntax/index.md) | -| 我要先核对语言核心事实 | [syntax/01_quickstart.md](syntax/01_quickstart.md) | -| 我要写最短可运行骨架 | [syntax/01_quickstart.md](syntax/01_quickstart.md) | -| 我要判断“这句语法能不能写” | [syntax/index.md](syntax/index.md) | -| 我要核对较新写法 / 新能力并入 / 资料冲突 / 解释器版本边界 | [syntax/index.md](syntax/index.md)，再按主题跳到对应语法页 | -| 我要核对高频误写 / 反例 / 负向边界 | [syntax/11_pitfalls.md](syntax/11_pitfalls.md) | -| 我要查行情 / 财务 / 板块 / 选股等金融函数 | [reference/catalog/datawarehouse.md](reference/catalog/datawarehouse.md) | -| 我要用 Python 调 TSL 服务器函数或取金融数据 | [modules/pytsl_api.md](modules/pytsl_api.md) | -| 我要写回测框架 / 读取回测结果 | [modules/tsbacktesting.md](modules/tsbacktesting.md) | -| 我要看模块 / 集成 / 互操作入口 | [modules/index.md](modules/index.md) | -| 我要确认账户体系 / 真实接口 / 部署方式 / 脚本入口 / 环境变量 / CI / 验证命令 | 项目自身文档、`scripts/*` 入口脚本、CI 配置；有项目文档时再看 [toolchain.md](toolchain.md) | -| 我要查函数库 | [reference/index.md](reference/index.md) | - -## 路由冲突处理 - -- 如果一个问题同时涉及业务和语法，先按主问题分层。 -- 如果主问题是业务实现，先走 `modules/`、`reference/catalog/datawarehouse.md` 或项目实际接口文档，语法只作辅证，不反过来吞掉业务入口。 -- 如果主问题是语言写法，先走 `syntax/`，金融或模块页只作为示例和上下文。 -- 如果主问题已经落到真实接入参数、账号来源、部署依赖、执行入口或权限模型，直接转“项目依赖 / 项目执行”确认，不继续在 `modules/`、`syntax/` 或模板型 `toolchain.md` 里兜圈子。 - -## 通用 TSL 语法骨架路径 - -只有主问题是语言写法、最短骨架或语法有效性时，才从本节起手；如果主问题是模块集成、函数库查询或项目执行，先回到“任务路由”。 - -1. 先看 [syntax/01_quickstart.md](syntax/01_quickstart.md) 的语言核心事实和最短骨架。 -2. 再按 [syntax/index.md](syntax/index.md) 进入命中的语法专题。 -3. 涉及反例、常见误写或负向边界时，看 [syntax/11_pitfalls.md](syntax/11_pitfalls.md)。 - -## 智能体提交前最低自检 - -1. 是否已经判断主问题属于语法、函数库、模块/集成或项目执行。 -2. 如果要生成代码，是否已经确认 `.tsl` / `.tsf` 文件模型。 -3. 是否优先参考了 `代码块身份：可直接照写示例`。 -4. 是否避开了 `反例 / 不可照写`、输出片段和概念骨架。 -5. 是否没有凭 Pascal、Python、JavaScript、TypeScript 或其它语言相似性补全 TSL 语法。 -6. 是否没有把项目执行信息、账户体系、真实接口或验证命令写成通用 TSL 事实。 -7. 仍不确定的地方是否明确说明，而不是隐藏在生成代码里。 +- 代码外形缺少 `代码块身份：可直接照写示例`。 +- 无文档事实、文件模型不明或项目执行事实缺失。 +- 需要复制反例、输出片段或概念骨架才能完成。 +- 需要凭 Pascal、Python、JavaScript、TypeScript 或 SQL 直觉补语法。 +- 项目执行信息会被写成通用 TSL 事实。 diff --git a/docs/tsl/naming.md b/docs/tsl/naming.md index 4d4a341e..94b98bc7 100644 --- a/docs/tsl/naming.md +++ b/docs/tsl/naming.md @@ -4,9 +4,9 @@ 是否可直接用于生成代码：仅部分 是否含可直接照写示例：否 是否含不可照写反例：否 -遇到不确定时：[code_style.md](code_style.md)、[syntax/index.md](syntax/index.md)、[syntax/02_core_model.md](syntax/02_core_model.md) +遇到不确定时：命名对象不明看 [syntax/02_core_model.md](syntax/02_core_model.md)；代码组织看 [code_style.md](code_style.md)；语法事实看 [syntax/index.md](syntax/index.md) -本页记录本仓库/作者的命名偏好，不代表 TSL 语法事实。命名偏好与 Google C++ Style Guide 的实体形状思路对齐：通过名字的“形状”快速判断实体类型（类型/函数/变量/常量等），减少阅读成本。 +本页记录本仓库/作者的命名偏好，不代表 TSL 语法事实。本页只规定命名后的实体如何取名，不承担文件模型、顶层声明、执行顺序等语法判断。命名偏好与 Google C++ Style Guide 的实体形状思路对齐：通过名字的“形状”快速判断实体类型（类型/函数/变量/常量等），减少阅读成本。 以下出现的 `<...>` 形式只表示命名或注释模板占位，不是源码字面量。 @@ -49,8 +49,7 @@ ## 3. 类型命名（Type Names） -AI 先按 `.tsl` 可执行脚本与 `.tsf` 模块/函数扩展判断文件模型。`.tsl` 里的语句区按顺序执行，函数/类声明区放在语句区之后；`.tsf` 用于可复用顶层声明并部署到解释器 `funcext`。本页只覆盖“需要命名的顶层实体”，不覆盖脚本语句本身；文件模型判断本身以 -`docs/tsl/syntax/02_core_model.md` 为准。 +文件模型和顶层声明规则以 `docs/tsl/syntax/02_core_model.md` 为准。本页只覆盖“需要命名的顶层实体”，不覆盖脚本语句本身。 - **类与单元**使用 `PascalCase`，不带下划线；名称应为名词/名词短语（通常单数），避免动词开头。 @@ -65,20 +64,13 @@ AI 先按 `.tsl` 可执行脚本与 `.tsf` 模块/函数扩展判断文件模型 ## 4. 文件命名与顶层声明（File Names） -TSL 的语法要求（仅 `.tsf`）：每个 `.tsf` -文件只能有一个顶层声明，且**文件基名必须与该顶层声明名字一致**。 +文件模型、可写顶层声明、声明与文件关系以 +`docs/tsl/syntax/02_core_model.md` 为准；本节只给已经确定要命名的文件/实体提供命名偏好。 -- 更可靠的判断方式仍然是先看顶层内容，而不是只看扩展名；命名偏好只是补充“命名后的实体如何取名”，不替代文件模型判断。 +- 先用核心模型页判断目标是否存在需要命名的顶层实体；不要从本页反推 + `.tsl` / `.tsf` 可写结构。 - 需要命名的顶层实体可以是 `function / procedure`、`type Name = class`、`unit`。 -- `.tsf` 代码文件：用于库/模块等“顶层声明”的首选承载文件；顶层声明可为 - `function / procedure`、`type Name = class`、`unit`，文件基名需与之同名。 -- `.tsl` 脚本文件：用于入口/编排层；允许直接写语句（如 - `a := 1; echo a;`），也可能出现顶层 `function / procedure` 骨架 - 这类示例脚本外壳；如果同时出现脚本语句和函数/类声明，语句区在前，声明区在后；但风格上不把 `.tsl` 当成可复用顶层声明的默认落点，也不要求文件基名与函数名一致；可复用逻辑优先下沉到 - `.tsf`（见 `docs/tsl/code_style.md`）。 - - 注：`.tsf` 也是 TSL 源文件，命名/风格与 `.tsl` 遵循同一套规则。 -- **硬规则（仅 - `.tsf`）**：重命名顶层声明时必须同步重命名文件基名，否则语法/加载规则无法识别；批量重命名时也必须把这两处一起改掉。 +- 批量重命名时，把文件基名和顶层实体名作为同一组维护，避免检索和协作断裂。 命名建议： diff --git a/docs/tsl/reference/catalog/base.md b/docs/tsl/reference/catalog/base.md index 07e0a6c1..6afdd8de 100644 --- a/docs/tsl/reference/catalog/base.md +++ b/docs/tsl/reference/catalog/base.md @@ -23,32 +23,28 @@ | 分类 | 详情页 | 函数事实数 | | ---------------------------- | ------------------------------------------------------------------------------ | ---------: | | 常用日期时间函数 | [base/01_common_datetime.md](base/01_common_datetime.md) | 32 | -| 简单转换函数 | [base/02_simple_conversion.md](base/02_simple_conversion.md) | 2 | -| 普通日期函数 | [base/03_date_basic.md](base/03_date_basic.md) | 19 | -| 分解函数 | [base/04_datetime_parts.md](base/04_datetime_parts.md) | 9 | -| 起始结束函数 | [base/05_datetime_boundaries.md](base/05_datetime_boundaries.md) | 16 | -| 关系函数 | [base/06_datetime_relations.md](base/06_datetime_relations.md) | 28 | -| 范围判定函数 | [base/07_range_predicates.md](base/07_range_predicates.md) | 8 | -| 范围获得函数 | [base/08_range_getters.md](base/08_range_getters.md) | 8 | -| 范围生成函数 | [base/09_range_span.md](base/09_range_span.md) | 8 | -| 时间推移函数 | [base/10_time_shift.md](base/10_time_shift.md) | 8 | -| 组合、分解日期函数 | [base/11_compose_decompose_datetime.md](base/11_compose_decompose_datetime.md) | 11 | -| 日期重组函数 | [base/12_datetime_recode.md](base/12_datetime_recode.md) | 21 | -| 日期格式的转换 | [base/13_datetime_format_conversion.md](base/13_datetime_format_conversion.md) | 10 | -| 宽字节日期格式转换函数 | [base/14_wide_datetime_conversion.md](base/14_wide_datetime_conversion.md) | 6 | -| 常用字符串函数 | [base/15_string_common.md](base/15_string_common.md) | 69 | -| 判定函数 | [base/16_string_predicates.md](base/16_string_predicates.md) | 8 | -| 替换以及处理函数 | [base/17_string_replace_process.md](base/17_string_replace_process.md) | 8 | -| 字符串数组相关函数 | [base/18_string_array.md](base/18_string_array.md) | 2 | -| 重复函数 | [base/19_repeat.md](base/19_repeat.md) | 1 | -| 多字节语言支持函数 | [base/20_multibyte_language.md](base/20_multibyte_language.md) | 2 | -| 字节函数 | [base/21_byte.md](base/21_byte.md) | 8 | -| 发音相关函数 | [base/22_phonetic.md](base/22_phonetic.md) | 10 | -| 正则表达式函数 | [base/23_regex.md](base/23_regex.md) | 3 | -| 多语言支持函数 | [base/24_multilanguage.md](base/24_multilanguage.md) | 33 | -| 文件名以及目录名相关处理函数 | [base/25_path_filename.md](base/25_path_filename.md) | 18 | -| 基本 | [base/26_array_basic.md](base/26_array_basic.md) | 4 | -| 数组下标以及长度相关函数 | [base/27_array_index_length.md](base/27_array_index_length.md) | 7 | -| 排序函数 | [base/28_array_sort.md](base/28_array_sort.md) | 2 | -| 增删改查 | [base/29_array_crud.md](base/29_array_crud.md) | 6 | -| 重构函数 | [base/30_array_restructure.md](base/30_array_restructure.md) | 2 | +| 字符串数组与重复函数 | [base/17_string_array_and_repeat.md](base/17_string_array_and_repeat.md) | 3 | +| 普通日期函数 | [base/02_date_basic.md](base/02_date_basic.md) | 19 | +| 分解函数 | [base/03_datetime_parts.md](base/03_datetime_parts.md) | 9 | +| 起始结束函数 | [base/04_datetime_boundaries.md](base/04_datetime_boundaries.md) | 16 | +| 关系函数 | [base/05_datetime_relations.md](base/05_datetime_relations.md) | 28 | +| 范围判定函数 | [base/06_range_predicates.md](base/06_range_predicates.md) | 8 | +| 范围获得函数 | [base/07_range_getters.md](base/07_range_getters.md) | 8 | +| 范围生成函数 | [base/08_range_span.md](base/08_range_span.md) | 8 | +| 时间推移函数 | [base/09_time_shift.md](base/09_time_shift.md) | 8 | +| 组合、分解日期函数 | [base/10_compose_decompose_datetime.md](base/10_compose_decompose_datetime.md) | 11 | +| 日期重组函数 | [base/11_datetime_recode.md](base/11_datetime_recode.md) | 21 | +| 日期格式的转换 | [base/12_datetime_format_conversion.md](base/12_datetime_format_conversion.md) | 10 | +| 宽字节日期格式转换函数 | [base/13_wide_datetime_conversion.md](base/13_wide_datetime_conversion.md) | 6 | +| 数组排序与重构 | [base/25_array_sort_and_operations.md](base/25_array_sort_and_operations.md) | 4 | +| 常用字符串函数 | [base/14_string_common.md](base/14_string_common.md) | 69 | +| 判定函数 | [base/15_string_predicates.md](base/15_string_predicates.md) | 8 | +| 替换以及处理函数 | [base/16_string_replace_process.md](base/16_string_replace_process.md) | 8 | +| 字节函数 | [base/18_byte.md](base/18_byte.md) | 8 | +| 发音相关函数 | [base/19_phonetic.md](base/19_phonetic.md) | 10 | +| 正则表达式函数 | [base/20_regex.md](base/20_regex.md) | 3 | +| 多语言支持函数 | [base/21_multilanguage.md](base/21_multilanguage.md) | 33 | +| 文件名以及目录名相关处理函数 | [base/22_path_filename.md](base/22_path_filename.md) | 18 | +| 基本 | [base/23_array_basic.md](base/23_array_basic.md) | 4 | +| 数组下标以及长度相关函数 | [base/24_array_index_length.md](base/24_array_index_length.md) | 7 | +| 增删改查 | [base/26_array_crud.md](base/26_array_crud.md) | 6 | diff --git a/docs/tsl/reference/catalog/base/03_date_basic.md b/docs/tsl/reference/catalog/base/02_date_basic.md similarity index 91% rename from docs/tsl/reference/catalog/base/03_date_basic.md rename to docs/tsl/reference/catalog/base/02_date_basic.md index d1fe96a5..9c4f96cc 100644 --- a/docs/tsl/reference/catalog/base/03_date_basic.md +++ b/docs/tsl/reference/catalog/base/02_date_basic.md @@ -230,3 +230,27 @@ | -------- | ------- | ---- | -------- | -------------------- | | 1 | `aday` | 是 | 整数 | 按源文档示例顺序传入 | | 2 | `today` | 是 | 整数 | 按源文档示例顺序传入 | + +## 简单转换函数 + +### `dateToInt(value)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | + +### `intToDate(value)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/02_simple_conversion.md b/docs/tsl/reference/catalog/base/02_simple_conversion.md deleted file mode 100644 index bad6f7ff..00000000 --- a/docs/tsl/reference/catalog/base/02_simple_conversion.md +++ /dev/null @@ -1,29 +0,0 @@ -# 基础函数 - 简单转换函数 - -文档类型：函数事实页 -是否可直接用于生成代码：是；本页函数条目均包含参数表 -遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) - -## 简单转换函数 - -### `dateToInt(value)` - -用途：日期时间处理函数。 - -参数个数：1 -返回值：日期或时间值 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------- | ---- | -------- | -------------------- | -| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | - -### `intToDate(value)` - -用途：日期时间处理函数。 - -参数个数：1 -返回值：日期或时间值 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------- | ---- | -------- | -------------------- | -| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/04_datetime_parts.md b/docs/tsl/reference/catalog/base/03_datetime_parts.md similarity index 100% rename from docs/tsl/reference/catalog/base/04_datetime_parts.md rename to docs/tsl/reference/catalog/base/03_datetime_parts.md diff --git a/docs/tsl/reference/catalog/base/05_datetime_boundaries.md b/docs/tsl/reference/catalog/base/04_datetime_boundaries.md similarity index 100% rename from docs/tsl/reference/catalog/base/05_datetime_boundaries.md rename to docs/tsl/reference/catalog/base/04_datetime_boundaries.md diff --git a/docs/tsl/reference/catalog/base/06_datetime_relations.md b/docs/tsl/reference/catalog/base/05_datetime_relations.md similarity index 100% rename from docs/tsl/reference/catalog/base/06_datetime_relations.md rename to docs/tsl/reference/catalog/base/05_datetime_relations.md diff --git a/docs/tsl/reference/catalog/base/07_range_predicates.md b/docs/tsl/reference/catalog/base/06_range_predicates.md similarity index 100% rename from docs/tsl/reference/catalog/base/07_range_predicates.md rename to docs/tsl/reference/catalog/base/06_range_predicates.md diff --git a/docs/tsl/reference/catalog/base/08_range_getters.md b/docs/tsl/reference/catalog/base/07_range_getters.md similarity index 100% rename from docs/tsl/reference/catalog/base/08_range_getters.md rename to docs/tsl/reference/catalog/base/07_range_getters.md diff --git a/docs/tsl/reference/catalog/base/09_range_span.md b/docs/tsl/reference/catalog/base/08_range_span.md similarity index 100% rename from docs/tsl/reference/catalog/base/09_range_span.md rename to docs/tsl/reference/catalog/base/08_range_span.md diff --git a/docs/tsl/reference/catalog/base/10_time_shift.md b/docs/tsl/reference/catalog/base/09_time_shift.md similarity index 100% rename from docs/tsl/reference/catalog/base/10_time_shift.md rename to docs/tsl/reference/catalog/base/09_time_shift.md diff --git a/docs/tsl/reference/catalog/base/11_compose_decompose_datetime.md b/docs/tsl/reference/catalog/base/10_compose_decompose_datetime.md similarity index 100% rename from docs/tsl/reference/catalog/base/11_compose_decompose_datetime.md rename to docs/tsl/reference/catalog/base/10_compose_decompose_datetime.md diff --git a/docs/tsl/reference/catalog/base/12_datetime_recode.md b/docs/tsl/reference/catalog/base/11_datetime_recode.md similarity index 100% rename from docs/tsl/reference/catalog/base/12_datetime_recode.md rename to docs/tsl/reference/catalog/base/11_datetime_recode.md diff --git a/docs/tsl/reference/catalog/base/13_datetime_format_conversion.md b/docs/tsl/reference/catalog/base/12_datetime_format_conversion.md similarity index 100% rename from docs/tsl/reference/catalog/base/13_datetime_format_conversion.md rename to docs/tsl/reference/catalog/base/12_datetime_format_conversion.md diff --git a/docs/tsl/reference/catalog/base/14_wide_datetime_conversion.md b/docs/tsl/reference/catalog/base/13_wide_datetime_conversion.md similarity index 100% rename from docs/tsl/reference/catalog/base/14_wide_datetime_conversion.md rename to docs/tsl/reference/catalog/base/13_wide_datetime_conversion.md diff --git a/docs/tsl/reference/catalog/base/15_string_common.md b/docs/tsl/reference/catalog/base/14_string_common.md similarity index 100% rename from docs/tsl/reference/catalog/base/15_string_common.md rename to docs/tsl/reference/catalog/base/14_string_common.md diff --git a/docs/tsl/reference/catalog/base/16_string_predicates.md b/docs/tsl/reference/catalog/base/15_string_predicates.md similarity index 100% rename from docs/tsl/reference/catalog/base/16_string_predicates.md rename to docs/tsl/reference/catalog/base/15_string_predicates.md diff --git a/docs/tsl/reference/catalog/base/17_string_replace_process.md b/docs/tsl/reference/catalog/base/16_string_replace_process.md similarity index 100% rename from docs/tsl/reference/catalog/base/17_string_replace_process.md rename to docs/tsl/reference/catalog/base/16_string_replace_process.md diff --git a/docs/tsl/reference/catalog/base/18_string_array.md b/docs/tsl/reference/catalog/base/17_string_array_and_repeat.md similarity index 69% rename from docs/tsl/reference/catalog/base/18_string_array.md rename to docs/tsl/reference/catalog/base/17_string_array_and_repeat.md index 1901df6c..7258e16c 100644 --- a/docs/tsl/reference/catalog/base/18_string_array.md +++ b/docs/tsl/reference/catalog/base/17_string_array_and_repeat.md @@ -1,4 +1,4 @@ -# 基础函数 - 字符串数组相关函数 +# 基础函数 - 字符串数组与重复函数 文档类型：函数事实页 是否可直接用于生成代码：是；本页函数条目均包含参数表 @@ -29,3 +29,17 @@ | -------- | --------- | ---- | -------- | -------------------- | | 1 | `eg_str` | 是 | 字符串 | 按源文档示例顺序传入 | | 2 | `str_arr` | 是 | 字符串 | 按源文档示例顺序传入 | + +## 重复函数 + +### `dupeString(value, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/21_byte.md b/docs/tsl/reference/catalog/base/18_byte.md similarity index 100% rename from docs/tsl/reference/catalog/base/21_byte.md rename to docs/tsl/reference/catalog/base/18_byte.md diff --git a/docs/tsl/reference/catalog/base/22_phonetic.md b/docs/tsl/reference/catalog/base/19_phonetic.md similarity index 100% rename from docs/tsl/reference/catalog/base/22_phonetic.md rename to docs/tsl/reference/catalog/base/19_phonetic.md diff --git a/docs/tsl/reference/catalog/base/19_repeat.md b/docs/tsl/reference/catalog/base/19_repeat.md deleted file mode 100644 index 14a3e29c..00000000 --- a/docs/tsl/reference/catalog/base/19_repeat.md +++ /dev/null @@ -1,19 +0,0 @@ -# 基础函数 - 重复函数 - -文档类型：函数事实页 -是否可直接用于生成代码：是；本页函数条目均包含参数表 -遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) - -## 重复函数 - -### `dupeString(value, arg2)` - -用途：字符串相关函数。 - -参数个数：2 -返回值：字符串 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------- | ---- | -------- | -------------------- | -| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | -| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/20_multibyte_language.md b/docs/tsl/reference/catalog/base/20_multibyte_language.md deleted file mode 100644 index 94c64229..00000000 --- a/docs/tsl/reference/catalog/base/20_multibyte_language.md +++ /dev/null @@ -1,31 +0,0 @@ -# 基础函数 - 多字节语言支持函数 - -文档类型：函数事实页 -是否可直接用于生成代码：是；本页函数条目均包含参数表 -遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) - -## 多字节语言支持函数 - -### `lengthW(test_str)` - -用途：字符串相关函数。 - -参数个数：1 -返回值：整数 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ---------- | ---- | -------- | -------------------- | -| 1 | `test_str` | 是 | 字符串 | 按源文档示例顺序传入 | - -### `midStr(test_str, arg2, arg3)` - -用途：字符串相关函数。 - -参数个数：3 -返回值：字符串 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ---------- | ---- | -------- | -------------------- | -| 1 | `test_str` | 是 | 字符串 | 按源文档示例顺序传入 | -| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | -| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/23_regex.md b/docs/tsl/reference/catalog/base/20_regex.md similarity index 100% rename from docs/tsl/reference/catalog/base/23_regex.md rename to docs/tsl/reference/catalog/base/20_regex.md diff --git a/docs/tsl/reference/catalog/base/24_multilanguage.md b/docs/tsl/reference/catalog/base/21_multilanguage.md similarity index 93% rename from docs/tsl/reference/catalog/base/24_multilanguage.md rename to docs/tsl/reference/catalog/base/21_multilanguage.md index 720e4553..798f5774 100644 --- a/docs/tsl/reference/catalog/base/24_multilanguage.md +++ b/docs/tsl/reference/catalog/base/21_multilanguage.md @@ -381,3 +381,29 @@ | 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | | -------- | ------ | ---- | -------- | -------------------- | | 1 | `s` | 是 | 数组 | 按源文档示例顺序传入 | + +## 多字节语言支持函数（补充） + +### `lengthW(test_str)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `test_str` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `midStr(test_str, arg2, arg3)` + +用途：字符串相关函数。 + +参数个数：3 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `test_str` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/25_path_filename.md b/docs/tsl/reference/catalog/base/22_path_filename.md similarity index 100% rename from docs/tsl/reference/catalog/base/25_path_filename.md rename to docs/tsl/reference/catalog/base/22_path_filename.md diff --git a/docs/tsl/reference/catalog/base/26_array_basic.md b/docs/tsl/reference/catalog/base/23_array_basic.md similarity index 100% rename from docs/tsl/reference/catalog/base/26_array_basic.md rename to docs/tsl/reference/catalog/base/23_array_basic.md diff --git a/docs/tsl/reference/catalog/base/27_array_index_length.md b/docs/tsl/reference/catalog/base/24_array_index_length.md similarity index 100% rename from docs/tsl/reference/catalog/base/27_array_index_length.md rename to docs/tsl/reference/catalog/base/24_array_index_length.md diff --git a/docs/tsl/reference/catalog/base/30_array_restructure.md b/docs/tsl/reference/catalog/base/25_array_sort_and_operations.md similarity index 57% rename from docs/tsl/reference/catalog/base/30_array_restructure.md rename to docs/tsl/reference/catalog/base/25_array_sort_and_operations.md index b53ad4ba..c666bddf 100644 --- a/docs/tsl/reference/catalog/base/30_array_restructure.md +++ b/docs/tsl/reference/catalog/base/25_array_sort_and_operations.md @@ -1,9 +1,35 @@ -# 基础函数 - 重构函数 +# 基础函数 - 数组排序与重构函数 文档类型：函数事实页 是否可直接用于生成代码：是；本页函数条目均包含参数表 遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) +## 排序函数 + +### `sortArray(arr)` + +用途：排序函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arr` | 是 | 数组 | 按源文档示例顺序传入 | + +### `sortTableByField(arr, arg2, arg3)` + +用途：排序函数相关函数。 + +参数个数：3 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arr` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + ## 重构函数 ### `reIndex(a, arg2[, s])` @@ -28,6 +54,6 @@ | 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | | -------- | ------ | ---- | -------- | -------------------- | -| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 1 | `a` | 是 | 组 | 按源文档示例顺序传入 | | 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | | 3 | `arg3` | 否 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/29_array_crud.md b/docs/tsl/reference/catalog/base/26_array_crud.md similarity index 100% rename from docs/tsl/reference/catalog/base/29_array_crud.md rename to docs/tsl/reference/catalog/base/26_array_crud.md diff --git a/docs/tsl/reference/catalog/base/28_array_sort.md b/docs/tsl/reference/catalog/base/28_array_sort.md deleted file mode 100644 index 48b09ecb..00000000 --- a/docs/tsl/reference/catalog/base/28_array_sort.md +++ /dev/null @@ -1,31 +0,0 @@ -# 基础函数 - 排序函数 - -文档类型：函数事实页 -是否可直接用于生成代码：是；本页函数条目均包含参数表 -遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) - -## 排序函数 - -### `sortArray(arr)` - -用途：排序函数相关函数。 - -参数个数：1 -返回值：处理结果 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------ | ---- | -------- | -------------------- | -| 1 | `arr` | 是 | 数组 | 按源文档示例顺序传入 | - -### `sortTableByField(arr, arg2, arg3)` - -用途：排序函数相关函数。 - -参数个数：3 -返回值：处理结果 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------ | ---- | -------- | -------------------- | -| 1 | `arr` | 是 | 数组 | 按源文档示例顺序传入 | -| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | -| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/datawarehouse.md b/docs/tsl/reference/catalog/datawarehouse.md index bf8ee87c..7d7da81b 100644 --- a/docs/tsl/reference/catalog/datawarehouse.md +++ b/docs/tsl/reference/catalog/datawarehouse.md @@ -23,34 +23,27 @@ | 分类 | 详情页 | 函数事实数 | | -------------------------- | -------------------------------------------------------------------------------------------------------- | ---------: | -| 系统参数键 | [datawarehouse/01_system_param_keys.md](datawarehouse/01_system_param_keys.md) | 1 | -| 系统参数名称函数 | [datawarehouse/02_system_param_names.md](datawarehouse/02_system_param_names.md) | 17 | -| 多市场支撑函数 | [datawarehouse/03_multi_market.md](datawarehouse/03_multi_market.md) | 5 | -| 时间相关函数 | [datawarehouse/04_time.md](datawarehouse/04_time.md) | 4 | -| 判定函数 | [datawarehouse/05_predicates.md](datawarehouse/05_predicates.md) | 14 | -| 盘中相关 | [datawarehouse/06_intraday.md](datawarehouse/06_intraday.md) | 1 | -| 盘后相关(在当日可用于盘中) | [datawarehouse/07_after_close_intraday_available.md](datawarehouse/07_after_close_intraday_available.md) | 63 | -| 时间序列统计 | [datawarehouse/08_time_series_stats.md](datawarehouse/08_time_series_stats.md) | 40 | -| 成交明细数据函数 | [datawarehouse/09_transaction_detail_data.md](datawarehouse/09_transaction_detail_data.md) | 9 | -| 交易明细字段标识函数 | [datawarehouse/10_transaction_detail_fields.md](datawarehouse/10_transaction_detail_fields.md) | 28 | -| 查询和轮询函数 | [datawarehouse/11_query_polling.md](datawarehouse/11_query_polling.md) | 1 | -| 市场和板块函数 | [datawarehouse/12_market_sector.md](datawarehouse/12_market_sector.md) | 5 | -| 取行情数据序列函数 | [datawarehouse/13_quote_series.md](datawarehouse/13_quote_series.md) | 3 | -| 引用指定函数 | [datawarehouse/14_reference_functions.md](datawarehouse/14_reference_functions.md) | 4 | -| 系统参数设置和获取函数 | [datawarehouse/15_sys_param_access.md](datawarehouse/15_sys_param_access.md) | 4 | -| 复权类型函数 | [datawarehouse/16_reinstatement_types.md](datawarehouse/16_reinstatement_types.md) | 3 | -| 复权基准日函数 | [datawarehouse/17_reinstatement_base_date.md](datawarehouse/17_reinstatement_base_date.md) | 2 | -| 周期函数 | [datawarehouse/18_cycle.md](datawarehouse/18_cycle.md) | 34 | -| 财务函数 | [datawarehouse/19_financial.md](datawarehouse/19_financial.md) | 18 | -| 选股与取数 | [datawarehouse/20_selection_and_fetch.md](datawarehouse/20_selection_and_fetch.md) | 6 | -| 向导函数 | [datawarehouse/21_wizard.md](datawarehouse/21_wizard.md) | 22 | -| 向导函数 / N期 | [datawarehouse/22_wizard_n_periods.md](datawarehouse/22_wizard_n_periods.md) | 18 | -| 向导函数 / N日 | [datawarehouse/23_wizard_n_days.md](datawarehouse/23_wizard_n_days.md) | 38 | -| 向导函数 / N日 / 中间函数 | [datawarehouse/24_wizard_n_days_intermediate.md](datawarehouse/24_wizard_n_days_intermediate.md) | 2 | -| 向导函数 / 历史遗留 | [datawarehouse/25_wizard_legacy.md](datawarehouse/25_wizard_legacy.md) | 2 | -| 向导函数 / 区间 | [datawarehouse/26_wizard_range.md](datawarehouse/26_wizard_range.md) | 32 | -| 向导函数 / 中间函数 | [datawarehouse/27_wizard_intermediate.md](datawarehouse/27_wizard_intermediate.md) | 8 | -| 向导函数 / N季 | [datawarehouse/28_wizard_n_quarters.md](datawarehouse/28_wizard_n_quarters.md) | 6 | -| 向导函数 / 当日 | [datawarehouse/29_wizard_today.md](datawarehouse/29_wizard_today.md) | 16 | -| 向导函数 / 当日 / 中间函数 | [datawarehouse/30_wizard_today_intermediate.md](datawarehouse/30_wizard_today_intermediate.md) | 7 | -| 条件判定 | [datawarehouse/31_condition_predicates.md](datawarehouse/31_condition_predicates.md) | 1 | +| 系统参数名称函数 | [datawarehouse/01_system_param_names.md](datawarehouse/01_system_param_names.md) | 17 | +| 多市场支撑函数 | [datawarehouse/02_multi_market.md](datawarehouse/02_multi_market.md) | 5 | +| 日内数据与收盘后可用 | [datawarehouse/05_intraday_and_after_close.md](datawarehouse/05_intraday_and_after_close.md) | 2 | +| 时间相关函数 | [datawarehouse/03_time.md](datawarehouse/03_time.md) | 4 | +| 判定函数 | [datawarehouse/04_predicates.md](datawarehouse/04_predicates.md) | 14 | +| 时间序列统计 | [datawarehouse/06_time_series_stats.md](datawarehouse/06_time_series_stats.md) | 40 | +| 成交明细数据函数 | [datawarehouse/07_transaction_detail_data.md](datawarehouse/07_transaction_detail_data.md) | 9 | +| 交易明细字段标识函数 | [datawarehouse/08_transaction_detail_fields.md](datawarehouse/08_transaction_detail_fields.md) | 28 | +| 市场和板块函数 | [datawarehouse/09_market_sector.md](datawarehouse/09_market_sector.md) | 5 | +| 取行情数据序列函数 | [datawarehouse/10_quote_series.md](datawarehouse/10_quote_series.md) | 3 | +| 引用指定函数 | [datawarehouse/11_reference_functions.md](datawarehouse/11_reference_functions.md) | 4 | +| 系统参数设置和获取函数 | [datawarehouse/12_sys_param_access.md](datawarehouse/12_sys_param_access.md) | 4 | +| 复权相关 | [datawarehouse/13_reinstatement.md](datawarehouse/13_reinstatement.md) | 5 | +| 周期函数 | [datawarehouse/14_cycle.md](datawarehouse/14_cycle.md) | 34 | +| 财务函数 | [datawarehouse/15_financial.md](datawarehouse/15_financial.md) | 18 | +| 选股与取数 | [datawarehouse/16_selection_and_fetch.md](datawarehouse/16_selection_and_fetch.md) | 6 | +| 向导函数 | [datawarehouse/17_wizard.md](datawarehouse/17_wizard.md) | 22 | +| 向导函数 / N期 | [datawarehouse/18_wizard_n_periods.md](datawarehouse/18_wizard_n_periods.md) | 18 | +| 向导函数 / N日 | [datawarehouse/19_wizard_n_days.md](datawarehouse/19_wizard_n_days.md) | 38 | +| 向导函数 / 区间 | [datawarehouse/20_wizard_range.md](datawarehouse/20_wizard_range.md) | 32 | +| 向导函数 / 中间函数 | [datawarehouse/21_wizard_intermediate.md](datawarehouse/21_wizard_intermediate.md) | 8 | +| 向导函数 / N季 | [datawarehouse/22_wizard_n_quarters.md](datawarehouse/22_wizard_n_quarters.md) | 6 | +| 向导函数 / 当日 | [datawarehouse/23_wizard_today.md](datawarehouse/23_wizard_today.md) | 16 | +| 向导函数 / 当日 / 中间函数 | [datawarehouse/24_wizard_today_intermediate.md](datawarehouse/24_wizard_today_intermediate.md) | 7 | diff --git a/docs/tsl/reference/catalog/datawarehouse/01_system_param_keys.md b/docs/tsl/reference/catalog/datawarehouse/01_system_param_keys.md deleted file mode 100644 index f46b6e83..00000000 --- a/docs/tsl/reference/catalog/datawarehouse/01_system_param_keys.md +++ /dev/null @@ -1,18 +0,0 @@ -# 数据仓库金融函数 - 系统参数键 - -文档类型：函数事实页 -是否可直接用于生成代码：是；本页函数条目均包含参数表 -遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) - -## 系统参数键 - -### `cyclefilter` - -用途：设置周期过滤器以及集合竞价分离器。它是系统参数键，不是函数调用。 - -参数个数：不适用 -返回值：不适用 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------- | ---- | -------- | ------------------------------------------------------------------------------------------------------------- | -| 1 | `value` | 是 | 整数 | 通过 `setSysParam("cyclefilter", value)` 设置；`0` 取消过滤，`1` 过滤期货放假期间夜盘，`3` 新增集合竞价周期点 | diff --git a/docs/tsl/reference/catalog/datawarehouse/02_system_param_names.md b/docs/tsl/reference/catalog/datawarehouse/01_system_param_names.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/02_system_param_names.md rename to docs/tsl/reference/catalog/datawarehouse/01_system_param_names.md diff --git a/docs/tsl/reference/catalog/datawarehouse/03_multi_market.md b/docs/tsl/reference/catalog/datawarehouse/02_multi_market.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/03_multi_market.md rename to docs/tsl/reference/catalog/datawarehouse/02_multi_market.md diff --git a/docs/tsl/reference/catalog/datawarehouse/04_time.md b/docs/tsl/reference/catalog/datawarehouse/03_time.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/04_time.md rename to docs/tsl/reference/catalog/datawarehouse/03_time.md diff --git a/docs/tsl/reference/catalog/datawarehouse/05_predicates.md b/docs/tsl/reference/catalog/datawarehouse/04_predicates.md similarity index 90% rename from docs/tsl/reference/catalog/datawarehouse/05_predicates.md rename to docs/tsl/reference/catalog/datawarehouse/04_predicates.md index 593c9d92..648a3eef 100644 --- a/docs/tsl/reference/catalog/datawarehouse/05_predicates.md +++ b/docs/tsl/reference/catalog/datawarehouse/04_predicates.md @@ -161,3 +161,21 @@ | 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | | -------- | ------ | ---- | -------- | -------------------------------------------- | | 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `46002` | +# 数据仓库金融函数 - 条件判定 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 条件判定 + +### `isTimePeriodInfoId(arg1)` + +用途：条件判定相关函数。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `150003` | diff --git a/docs/tsl/reference/catalog/datawarehouse/07_after_close_intraday_available.md b/docs/tsl/reference/catalog/datawarehouse/05_intraday_and_after_close.md similarity index 95% rename from docs/tsl/reference/catalog/datawarehouse/07_after_close_intraday_available.md rename to docs/tsl/reference/catalog/datawarehouse/05_intraday_and_after_close.md index 8a8308c1..f028c817 100644 --- a/docs/tsl/reference/catalog/datawarehouse/07_after_close_intraday_available.md +++ b/docs/tsl/reference/catalog/datawarehouse/05_intraday_and_after_close.md @@ -1,3 +1,21 @@ +# 数据仓库金融函数 - 日内数据 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 盘中相关 + +### `rd(arg1)` + +用途：盘中相关相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | # 数据仓库金融函数 - 盘后相关(在当日可用于盘中) 文档类型：函数事实页 diff --git a/docs/tsl/reference/catalog/datawarehouse/06_intraday.md b/docs/tsl/reference/catalog/datawarehouse/06_intraday.md deleted file mode 100644 index bf550a43..00000000 --- a/docs/tsl/reference/catalog/datawarehouse/06_intraday.md +++ /dev/null @@ -1,18 +0,0 @@ -# 数据仓库金融函数 - 盘中相关 - -文档类型：函数事实页 -是否可直接用于生成代码：是；本页函数条目均包含参数表 -遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) - -## 盘中相关 - -### `rd(arg1)` - -用途：盘中相关相关函数。 - -参数个数：1 -返回值：处理后的结果值 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------ | ---- | -------- | ---------------------------------------- | -| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | diff --git a/docs/tsl/reference/catalog/datawarehouse/08_time_series_stats.md b/docs/tsl/reference/catalog/datawarehouse/06_time_series_stats.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/08_time_series_stats.md rename to docs/tsl/reference/catalog/datawarehouse/06_time_series_stats.md diff --git a/docs/tsl/reference/catalog/datawarehouse/09_transaction_detail_data.md b/docs/tsl/reference/catalog/datawarehouse/07_transaction_detail_data.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/09_transaction_detail_data.md rename to docs/tsl/reference/catalog/datawarehouse/07_transaction_detail_data.md diff --git a/docs/tsl/reference/catalog/datawarehouse/10_transaction_detail_fields.md b/docs/tsl/reference/catalog/datawarehouse/08_transaction_detail_fields.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/10_transaction_detail_fields.md rename to docs/tsl/reference/catalog/datawarehouse/08_transaction_detail_fields.md diff --git a/docs/tsl/reference/catalog/datawarehouse/12_market_sector.md b/docs/tsl/reference/catalog/datawarehouse/09_market_sector.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/12_market_sector.md rename to docs/tsl/reference/catalog/datawarehouse/09_market_sector.md diff --git a/docs/tsl/reference/catalog/datawarehouse/13_quote_series.md b/docs/tsl/reference/catalog/datawarehouse/10_quote_series.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/13_quote_series.md rename to docs/tsl/reference/catalog/datawarehouse/10_quote_series.md diff --git a/docs/tsl/reference/catalog/datawarehouse/11_query_polling.md b/docs/tsl/reference/catalog/datawarehouse/11_query_polling.md deleted file mode 100644 index 04d518c9..00000000 --- a/docs/tsl/reference/catalog/datawarehouse/11_query_polling.md +++ /dev/null @@ -1,27 +0,0 @@ -# 数据仓库金融函数 - 查询和轮询函数 - -文档类型：函数事实页 -是否可直接用于生成代码：是；本页函数条目均包含参数表 -遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) - -## 查询和轮询函数 - -### `query(arg1, stock_id_2, arg3, arg4, arg5, stock_id_6, arg7, stock_id_8, arg9, arg10)` - -用途：查询和轮询函数相关函数。 - -参数个数：10 -返回值：处理后的结果值 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------------ | ---- | -------- | ------------------------------------------------------------------- | -| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'上证A股;创业板'` | -| 2 | `stock_id_2` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'SZ000001;SZ000002;SZ000997'` | -| 3 | `arg3` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close() > ma(close(), 10)` | -| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `''` | -| 5 | `arg5` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'证券代码'` | -| 6 | `stock_id_6` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `DefaultStockID()` | -| 7 | `arg7` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'证券名称'` | -| 8 | `stock_id_8` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `CurrentStockName()` | -| 9 | `arg9` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'收盘价'` | -| 10 | `arg10` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | diff --git a/docs/tsl/reference/catalog/datawarehouse/14_reference_functions.md b/docs/tsl/reference/catalog/datawarehouse/11_reference_functions.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/14_reference_functions.md rename to docs/tsl/reference/catalog/datawarehouse/11_reference_functions.md diff --git a/docs/tsl/reference/catalog/datawarehouse/15_sys_param_access.md b/docs/tsl/reference/catalog/datawarehouse/12_sys_param_access.md similarity index 76% rename from docs/tsl/reference/catalog/datawarehouse/15_sys_param_access.md rename to docs/tsl/reference/catalog/datawarehouse/12_sys_param_access.md index cf697bce..24de0fd8 100644 --- a/docs/tsl/reference/catalog/datawarehouse/15_sys_param_access.md +++ b/docs/tsl/reference/catalog/datawarehouse/12_sys_param_access.md @@ -51,3 +51,16 @@ | 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | | -------- | ---------- | ---- | -------- | ------------------------------------------------- | | 1 | `stock_id` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `pn_stock()` | + +## 系统参数键 + +### `cyclefilter` + +用途：设置周期过滤器以及集合竞价分离器。它是系统参数键，不是函数调用。 + +参数个数：不适用 +返回值：不适用 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------------------------------------------------------------------- | +| 1 | `value` | 是 | 整数 | 通过 `setSysParam("cyclefilter", value)` 设置；`0` 取消过滤，`1` 过滤期货放假期间夜盘，`3` 新增集合竞价周期点 | diff --git a/docs/tsl/reference/catalog/datawarehouse/16_reinstatement_types.md b/docs/tsl/reference/catalog/datawarehouse/13_reinstatement.md similarity index 53% rename from docs/tsl/reference/catalog/datawarehouse/16_reinstatement_types.md rename to docs/tsl/reference/catalog/datawarehouse/13_reinstatement.md index c4922454..5f444f82 100644 --- a/docs/tsl/reference/catalog/datawarehouse/16_reinstatement_types.md +++ b/docs/tsl/reference/catalog/datawarehouse/13_reinstatement.md @@ -1,4 +1,4 @@ -# 数据仓库金融函数 - 复权类型函数 +# 数据仓库金融函数 - 复权相关 文档类型：函数事实页 是否可直接用于生成代码：是；本页函数条目均包含参数表 @@ -35,3 +35,30 @@ | 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | | -------- | ------ | ---- | -------- | ---- | +# 数据仓库金融函数 - 复权基准日函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 复权基准日函数 + +### `rd_lastday()` + +用途：复权基准日函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `rd_firstday()` + +用途：复权基准日函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/datawarehouse/18_cycle.md b/docs/tsl/reference/catalog/datawarehouse/14_cycle.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/18_cycle.md rename to docs/tsl/reference/catalog/datawarehouse/14_cycle.md diff --git a/docs/tsl/reference/catalog/datawarehouse/19_financial.md b/docs/tsl/reference/catalog/datawarehouse/15_financial.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/19_financial.md rename to docs/tsl/reference/catalog/datawarehouse/15_financial.md diff --git a/docs/tsl/reference/catalog/datawarehouse/20_selection_and_fetch.md b/docs/tsl/reference/catalog/datawarehouse/16_selection_and_fetch.md similarity index 79% rename from docs/tsl/reference/catalog/datawarehouse/20_selection_and_fetch.md rename to docs/tsl/reference/catalog/datawarehouse/16_selection_and_fetch.md index 9e5af3b5..df808b15 100644 --- a/docs/tsl/reference/catalog/datawarehouse/20_selection_and_fetch.md +++ b/docs/tsl/reference/catalog/datawarehouse/16_selection_and_fetch.md @@ -102,3 +102,30 @@ | 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | | -------- | ------ | ---- | -------- | -------------------------------------------- | | 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'1+3'` | +# 数据仓库金融函数 - 查询和轮询函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 查询和轮询函数 + +### `query(arg1, stock_id_2, arg3, arg4, arg5, stock_id_6, arg7, stock_id_8, arg9, arg10)` + +用途：查询和轮询函数相关函数。 + +参数个数：10 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | ------------------------------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'上证A股;创业板'` | +| 2 | `stock_id_2` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'SZ000001;SZ000002;SZ000997'` | +| 3 | `arg3` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close() > ma(close(), 10)` | +| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `''` | +| 5 | `arg5` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'证券代码'` | +| 6 | `stock_id_6` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `DefaultStockID()` | +| 7 | `arg7` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'证券名称'` | +| 8 | `stock_id_8` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `CurrentStockName()` | +| 9 | `arg9` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'收盘价'` | +| 10 | `arg10` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | diff --git a/docs/tsl/reference/catalog/datawarehouse/17_reinstatement_base_date.md b/docs/tsl/reference/catalog/datawarehouse/17_reinstatement_base_date.md deleted file mode 100644 index f3795261..00000000 --- a/docs/tsl/reference/catalog/datawarehouse/17_reinstatement_base_date.md +++ /dev/null @@ -1,27 +0,0 @@ -# 数据仓库金融函数 - 复权基准日函数 - -文档类型：函数事实页 -是否可直接用于生成代码：是；本页函数条目均包含参数表 -遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) - -## 复权基准日函数 - -### `rd_lastday()` - -用途：复权基准日函数相关函数。 - -参数个数：0 -返回值：常量值 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------ | ---- | -------- | ---- | - -### `rd_firstday()` - -用途：复权基准日函数相关函数。 - -参数个数：0 -返回值：常量值 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/datawarehouse/21_wizard.md b/docs/tsl/reference/catalog/datawarehouse/17_wizard.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/21_wizard.md rename to docs/tsl/reference/catalog/datawarehouse/17_wizard.md diff --git a/docs/tsl/reference/catalog/datawarehouse/22_wizard_n_periods.md b/docs/tsl/reference/catalog/datawarehouse/18_wizard_n_periods.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/22_wizard_n_periods.md rename to docs/tsl/reference/catalog/datawarehouse/18_wizard_n_periods.md diff --git a/docs/tsl/reference/catalog/datawarehouse/23_wizard_n_days.md b/docs/tsl/reference/catalog/datawarehouse/19_wizard_n_days.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/23_wizard_n_days.md rename to docs/tsl/reference/catalog/datawarehouse/19_wizard_n_days.md diff --git a/docs/tsl/reference/catalog/datawarehouse/26_wizard_range.md b/docs/tsl/reference/catalog/datawarehouse/20_wizard_range.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/26_wizard_range.md rename to docs/tsl/reference/catalog/datawarehouse/20_wizard_range.md diff --git a/docs/tsl/reference/catalog/datawarehouse/27_wizard_intermediate.md b/docs/tsl/reference/catalog/datawarehouse/21_wizard_intermediate.md similarity index 66% rename from docs/tsl/reference/catalog/datawarehouse/27_wizard_intermediate.md rename to docs/tsl/reference/catalog/datawarehouse/21_wizard_intermediate.md index 7db10388..e5122ba5 100644 --- a/docs/tsl/reference/catalog/datawarehouse/27_wizard_intermediate.md +++ b/docs/tsl/reference/catalog/datawarehouse/21_wizard_intermediate.md @@ -105,3 +105,62 @@ | 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | | 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230101T` | | 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230110T` | +# 数据仓库金融函数 - 向导函数 / N日 / 中间函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 向导函数 / N日 / 中间函数 + +### `getExpCaceStr(expression)` + +用途：向导函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | + +### `techCal_unit(expression)` + +用途：向导函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +# 数据仓库金融函数 - 向导函数 / 历史遗留 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 向导函数 / 历史遗留 + +### `sumOfSectorExceptNoTrade(expression)` + +用途：进行数值统计计算。 + +参数个数：1 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | + +### `avgOfSectorExceptNoTrade(expression, arg2)` + +用途：进行数值统计计算。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | diff --git a/docs/tsl/reference/catalog/datawarehouse/28_wizard_n_quarters.md b/docs/tsl/reference/catalog/datawarehouse/22_wizard_n_quarters.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/28_wizard_n_quarters.md rename to docs/tsl/reference/catalog/datawarehouse/22_wizard_n_quarters.md diff --git a/docs/tsl/reference/catalog/datawarehouse/29_wizard_today.md b/docs/tsl/reference/catalog/datawarehouse/23_wizard_today.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/29_wizard_today.md rename to docs/tsl/reference/catalog/datawarehouse/23_wizard_today.md diff --git a/docs/tsl/reference/catalog/datawarehouse/24_wizard_n_days_intermediate.md b/docs/tsl/reference/catalog/datawarehouse/24_wizard_n_days_intermediate.md deleted file mode 100644 index 933e27ea..00000000 --- a/docs/tsl/reference/catalog/datawarehouse/24_wizard_n_days_intermediate.md +++ /dev/null @@ -1,29 +0,0 @@ -# 数据仓库金融函数 - 向导函数 / N日 / 中间函数 - -文档类型：函数事实页 -是否可直接用于生成代码：是；本页函数条目均包含参数表 -遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) - -## 向导函数 / N日 / 中间函数 - -### `getExpCaceStr(expression)` - -用途：向导函数相关函数。 - -参数个数：1 -返回值：处理后的结果值 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | -| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | - -### `techCal_unit(expression)` - -用途：向导函数相关函数。 - -参数个数：1 -返回值：处理后的结果值 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | -| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | diff --git a/docs/tsl/reference/catalog/datawarehouse/30_wizard_today_intermediate.md b/docs/tsl/reference/catalog/datawarehouse/24_wizard_today_intermediate.md similarity index 100% rename from docs/tsl/reference/catalog/datawarehouse/30_wizard_today_intermediate.md rename to docs/tsl/reference/catalog/datawarehouse/24_wizard_today_intermediate.md diff --git a/docs/tsl/reference/catalog/datawarehouse/25_wizard_legacy.md b/docs/tsl/reference/catalog/datawarehouse/25_wizard_legacy.md deleted file mode 100644 index 4637fc6a..00000000 --- a/docs/tsl/reference/catalog/datawarehouse/25_wizard_legacy.md +++ /dev/null @@ -1,30 +0,0 @@ -# 数据仓库金融函数 - 向导函数 / 历史遗留 - -文档类型：函数事实页 -是否可直接用于生成代码：是；本页函数条目均包含参数表 -遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) - -## 向导函数 / 历史遗留 - -### `sumOfSectorExceptNoTrade(expression)` - -用途：进行数值统计计算。 - -参数个数：1 -返回值：处理后的结果值。 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | -| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | - -### `avgOfSectorExceptNoTrade(expression, arg2)` - -用途：进行数值统计计算。 - -参数个数：2 -返回值：处理后的结果值。 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | -| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | -| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | diff --git a/docs/tsl/reference/catalog/datawarehouse/31_condition_predicates.md b/docs/tsl/reference/catalog/datawarehouse/31_condition_predicates.md deleted file mode 100644 index f2a22023..00000000 --- a/docs/tsl/reference/catalog/datawarehouse/31_condition_predicates.md +++ /dev/null @@ -1,18 +0,0 @@ -# 数据仓库金融函数 - 条件判定 - -文档类型：函数事实页 -是否可直接用于生成代码：是；本页函数条目均包含参数表 -遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) - -## 条件判定 - -### `isTimePeriodInfoId(arg1)` - -用途：条件判定相关函数。 - -参数个数：1 -返回值：布尔值 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------ | ---- | -------- | --------------------------------------------- | -| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `150003` | diff --git a/docs/tsl/reference/catalog/resource.md b/docs/tsl/reference/catalog/resource.md index 0af715cc..5a97b0ec 100644 --- a/docs/tsl/reference/catalog/resource.md +++ b/docs/tsl/reference/catalog/resource.md @@ -28,6 +28,5 @@ | 文件读写类型函数 | [resource/04_file_rw_types.md](resource/04_file_rw_types.md) | 7 | | 网络访问以及相关函数 | [resource/05_network.md](resource/05_network.md) | 9 | | INI文件处理函数 | [resource/06_ini.md](resource/06_ini.md) | 23 | -| 宽字节处理函数 | [resource/07_wide_byte.md](resource/07_wide_byte.md) | 1 | -| 进程相关函数 | [resource/08_process.md](resource/08_process.md) | 44 | -| 本地资源相关函数 | [resource/09_local_resource.md](resource/09_local_resource.md) | 8 | +| 进程相关函数 | [resource/07_process.md](resource/07_process.md) | 44 | +| 本地资源相关函数 | [resource/08_local_resource.md](resource/08_local_resource.md) | 8 | diff --git a/docs/tsl/reference/catalog/resource/02_file_access.md b/docs/tsl/reference/catalog/resource/02_file_access.md index 7a283c78..c8de796f 100644 --- a/docs/tsl/reference/catalog/resource/02_file_access.md +++ b/docs/tsl/reference/catalog/resource/02_file_access.md @@ -386,3 +386,20 @@ | 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入 | | 4 | `lj1` | 是 | 任意值 | 按源文档示例顺序传入 | | 5 | `arg5` | 否 | 整数 | 按源文档示例顺序传入 | +# 资源访问函数 - 宽字节处理函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../resource.md](../resource.md)、[../../index.md](../../index.md) + +## 宽字节处理函数 + +### `iniReadSectionsw()` + +用途：INI文件处理函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/resource/08_process.md b/docs/tsl/reference/catalog/resource/07_process.md similarity index 100% rename from docs/tsl/reference/catalog/resource/08_process.md rename to docs/tsl/reference/catalog/resource/07_process.md diff --git a/docs/tsl/reference/catalog/resource/07_wide_byte.md b/docs/tsl/reference/catalog/resource/07_wide_byte.md deleted file mode 100644 index 8a609cf7..00000000 --- a/docs/tsl/reference/catalog/resource/07_wide_byte.md +++ /dev/null @@ -1,17 +0,0 @@ -# 资源访问函数 - 宽字节处理函数 - -文档类型：函数事实页 -是否可直接用于生成代码：是；本页函数条目均包含参数表 -遇到不确定时：回到 [../resource.md](../resource.md)、[../../index.md](../../index.md) - -## 宽字节处理函数 - -### `iniReadSectionsw()` - -用途：INI文件处理函数相关函数。 - -参数个数：0 -返回值：处理后的结果值 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/resource/09_local_resource.md b/docs/tsl/reference/catalog/resource/08_local_resource.md similarity index 100% rename from docs/tsl/reference/catalog/resource/09_local_resource.md rename to docs/tsl/reference/catalog/resource/08_local_resource.md diff --git a/docs/tsl/reference/catalog/system.md b/docs/tsl/reference/catalog/system.md index 3d59a7dd..5604ece8 100644 --- a/docs/tsl/reference/catalog/system.md +++ b/docs/tsl/reference/catalog/system.md @@ -24,11 +24,7 @@ | ---------------- | ------------------------------------------------------------ | ---------: | | 数据类型函数 | [system/01_data_type.md](system/01_data_type.md) | 27 | | 数据类型转换函数 | [system/02_type_conversion.md](system/02_type_conversion.md) | 13 | -| 复制函数 | [system/03_copy.md](system/03_copy.md) | 1 | -| 全局缓存函数 | [system/04_global_cache.md](system/04_global_cache.md) | 4 | -| 随机函数 | [system/05_random.md](system/05_random.md) | 3 | -| 条件选择函数 | [system/06_conditional.md](system/06_conditional.md) | 1 | -| 表达式相关函数 | [system/07_expression.md](system/07_expression.md) | 5 | -| 性能优化相关函数 | [system/08_profiler.md](system/08_profiler.md) | 2 | -| 函数库路径 | [system/09_tsl_lib_path.md](system/09_tsl_lib_path.md) | 3 | -| 错误与断言函数 | [system/10_error_assertion.md](system/10_error_assertion.md) | 1 | +| 全局缓存函数 | [system/03_global_cache.md](system/03_global_cache.md) | 4 | +| 随机函数 | [system/04_random.md](system/04_random.md) | 3 | +| 表达式相关函数 | [system/05_expression.md](system/05_expression.md) | 5 | +| 函数库路径 | [system/06_tsl_lib_path.md](system/06_tsl_lib_path.md) | 3 | diff --git a/docs/tsl/reference/catalog/system/01_data_type.md b/docs/tsl/reference/catalog/system/01_data_type.md index 62e5f48d..88d3c272 100644 --- a/docs/tsl/reference/catalog/system/01_data_type.md +++ b/docs/tsl/reference/catalog/system/01_data_type.md @@ -333,3 +333,41 @@ | -------- | ----------- | ---- | -------- | ------------- | | 1 | `buffer` | 是 | 任意值 | Binary Buffer | | 2 | `type_name` | 是 | 字符串 | 类型名称 | +# 系统相关函数 - 复制函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../system.md](../system.md)、[../../index.md](../../index.md) + +## 复制函数 + +### `dupValue(value)` + +用途：复制值，避免被调用函数修改原变量。 + +参数个数：1 +返回值：复制后的值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------ | +| 1 | `value` | 是 | 整数 | 输入值 | +# 系统相关函数 - 条件选择函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../system.md](../system.md)、[../../index.md](../../index.md) + +## 条件选择函数 + +### `ifThen(condition, true_value, false_value)` + +用途：条件成立返回 true_value，否则返回 false_value。 + +参数个数：3 +返回值：true_value 或 false_value + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | ------------------ | +| 1 | `condition` | 是 | 整数 | 判断条件 | +| 2 | `true_value` | 是 | 整数 | 条件成立时返回值 | +| 3 | `false_value` | 是 | 整数 | 条件不成立时返回值 | diff --git a/docs/tsl/reference/catalog/system/03_copy.md b/docs/tsl/reference/catalog/system/03_copy.md deleted file mode 100644 index 687b427c..00000000 --- a/docs/tsl/reference/catalog/system/03_copy.md +++ /dev/null @@ -1,18 +0,0 @@ -# 系统相关函数 - 复制函数 - -文档类型：函数事实页 -是否可直接用于生成代码：是；本页函数条目均包含参数表 -遇到不确定时：回到 [../system.md](../system.md)、[../../index.md](../../index.md) - -## 复制函数 - -### `dupValue(value)` - -用途：复制值，避免被调用函数修改原变量。 - -参数个数：1 -返回值：复制后的值 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------- | ---- | -------- | ------ | -| 1 | `value` | 是 | 整数 | 输入值 | diff --git a/docs/tsl/reference/catalog/system/04_global_cache.md b/docs/tsl/reference/catalog/system/03_global_cache.md similarity index 100% rename from docs/tsl/reference/catalog/system/04_global_cache.md rename to docs/tsl/reference/catalog/system/03_global_cache.md diff --git a/docs/tsl/reference/catalog/system/05_random.md b/docs/tsl/reference/catalog/system/04_random.md similarity index 100% rename from docs/tsl/reference/catalog/system/05_random.md rename to docs/tsl/reference/catalog/system/04_random.md diff --git a/docs/tsl/reference/catalog/system/07_expression.md b/docs/tsl/reference/catalog/system/05_expression.md similarity index 100% rename from docs/tsl/reference/catalog/system/07_expression.md rename to docs/tsl/reference/catalog/system/05_expression.md diff --git a/docs/tsl/reference/catalog/system/06_conditional.md b/docs/tsl/reference/catalog/system/06_conditional.md deleted file mode 100644 index b2fe2727..00000000 --- a/docs/tsl/reference/catalog/system/06_conditional.md +++ /dev/null @@ -1,20 +0,0 @@ -# 系统相关函数 - 条件选择函数 - -文档类型：函数事实页 -是否可直接用于生成代码：是；本页函数条目均包含参数表 -遇到不确定时：回到 [../system.md](../system.md)、[../../index.md](../../index.md) - -## 条件选择函数 - -### `ifThen(condition, true_value, false_value)` - -用途：条件成立返回 true_value，否则返回 false_value。 - -参数个数：3 -返回值：true_value 或 false_value - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------------- | ---- | -------- | ------------------ | -| 1 | `condition` | 是 | 整数 | 判断条件 | -| 2 | `true_value` | 是 | 整数 | 条件成立时返回值 | -| 3 | `false_value` | 是 | 整数 | 条件不成立时返回值 | diff --git a/docs/tsl/reference/catalog/system/09_tsl_lib_path.md b/docs/tsl/reference/catalog/system/06_tsl_lib_path.md similarity index 100% rename from docs/tsl/reference/catalog/system/09_tsl_lib_path.md rename to docs/tsl/reference/catalog/system/06_tsl_lib_path.md diff --git a/docs/tsl/reference/catalog/system/10_error_assertion.md b/docs/tsl/reference/catalog/system/07_error_and_assertion.md similarity index 59% rename from docs/tsl/reference/catalog/system/10_error_assertion.md rename to docs/tsl/reference/catalog/system/07_error_and_assertion.md index feb11e09..f1a1fe95 100644 --- a/docs/tsl/reference/catalog/system/10_error_assertion.md +++ b/docs/tsl/reference/catalog/system/07_error_and_assertion.md @@ -1,4 +1,4 @@ -# 系统相关函数 - 错误与断言函数 +# 系统相关函数 - 错误处理与性能分析 文档类型：函数事实页 是否可直接用于生成代码：是；本页函数条目均包含参数表 @@ -25,3 +25,32 @@ - 真值示例：`1`、`true`、`-1`、`0.5`、`"abc"`、`array(1)`；通过时返回 `0`。 - 假值示例：`0`、`false`、`nil`、`""`、`array()`；失败时直接抛出 `error_message`。 - 断言失败不会把错误信息作为普通返回值交给调用方继续执行。 +# 系统相关函数 - 性能优化相关函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../system.md](../system.md)、[../../index.md](../../index.md) + +## 性能优化相关函数 + +### `setProfiler(flags)` + +用途：设置性能分析开关与统计范围。 + +参数个数：1 +返回值：无 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------- | +| 1 | `flags` | 是 | 整数 | 统计选项位掩码 | + +### `getProfilerInfo(mode)` + +用途：获取性能分析信息。 + +参数个数：1 +返回值：性能分析信息 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------- | +| 1 | `mode` | 是 | 整数 | 可选；传 1 仅返回信息不弹窗 | diff --git a/docs/tsl/reference/catalog/system/08_profiler.md b/docs/tsl/reference/catalog/system/08_profiler.md deleted file mode 100644 index 91869ca3..00000000 --- a/docs/tsl/reference/catalog/system/08_profiler.md +++ /dev/null @@ -1,29 +0,0 @@ -# 系统相关函数 - 性能优化相关函数 - -文档类型：函数事实页 -是否可直接用于生成代码：是；本页函数条目均包含参数表 -遇到不确定时：回到 [../system.md](../system.md)、[../../index.md](../../index.md) - -## 性能优化相关函数 - -### `setProfiler(flags)` - -用途：设置性能分析开关与统计范围。 - -参数个数：1 -返回值：无 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------- | ---- | -------- | -------------- | -| 1 | `flags` | 是 | 整数 | 统计选项位掩码 | - -### `getProfilerInfo(mode)` - -用途：获取性能分析信息。 - -参数个数：1 -返回值：性能分析信息 - -| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | -| -------- | ------ | ---- | -------- | --------------------------- | -| 1 | `mode` | 是 | 整数 | 可选；传 1 仅返回信息不弹窗 | diff --git a/docs/tsl/syntax/00_agent_index.json b/docs/tsl/syntax/00_agent_index.json new file mode 100644 index 00000000..dd5d780b --- /dev/null +++ b/docs/tsl/syntax/00_agent_index.json @@ -0,0 +1,218 @@ +{ + "version": "2.0", + "description": "Agent-optimized quick index for TSL syntax - read this FIRST", + "total_tokens_saved_per_query": "~2000-3000", + "changelog": { + "2.0": "Extended coverage from 7 to 14 scenarios, added understand_code and optimize_code decision paths", + "1.0": "Initial version with 7 high-frequency scenarios" + }, + + "intent_to_file": { + "hello_world": { + "file": "01_quickstart.md", + "line": 182, + "token_cost": 50, + "example": "echo \"hello\";" + }, + "function_basic": { + "file": "05_functions_and_calls.md", + "line": 103, + "token_cost": 100, + "example": "function Add(a, b);\nbegin\n return a + b;\nend;" + }, + "function_in_tsl": { + "file": "05_functions_and_calls.md", + "line": 82, + "token_cost": 150, + "example": "a := 1;\ntest();\n\nfunction test();\nbegin\n echo \"test\";\nend;" + }, + "procedure": { + "file": "05_functions_and_calls.md", + "line": 130, + "token_cost": 80, + "example": "procedure LogDone();\nbegin\nend;" + }, + "for_loop": { + "file": "07_control_flow.md", + "line": 89, + "token_cost": 100, + "example": "for i := 0 to 2 do\n sum := sum + i;" + }, + "while_loop": { + "file": "07_control_flow.md", + "line": 64, + "token_cost": 100, + "example": "counter := 0;\nwhile counter < 3 do\n counter := counter + 1;" + }, + "if_condition": { + "file": "07_control_flow.md", + "line": 54, + "token_cost": 120, + "example": "if flag > 0 then\nbegin\n value := 1;\nend" + }, + "assignment": { + "file": "06_expressions_and_operators.md", + "line": 136, + "token_cost": 60, + "example": "a := 1;" + }, + "variable_declaration": { + "file": "04_variables_and_constants.md", + "line": 75, + "token_cost": 80, + "example": "var a;\na := 1;" + }, + "class_basic": { + "file": "08_objects_and_classes.md", + "line": 98, + "token_cost": 200, + "example": "type Person = class\npublic\n name;\nend;" + }, + "class_in_tsl": { + "file": "08_objects_and_classes.md", + "line": 118, + "token_cost": 250, + "example": "obj := new MyClass();\nobj.value := 5;\n\ntype MyClass = class\npublic\n value;\nend;" + }, + "unit_import": { + "file": "09_units_and_scope.md", + "line": 141, + "token_cost": 60, + "example": "uses DemoUnit;" + }, + "unit_skeleton": { + "file": "09_units_and_scope.md", + "line": 56, + "token_cost": 200, + "example": "unit DemoUnit;\n\ninterface\n\nfunction Ping();\n\nimplementation\n\nfunction Ping();\nbegin\n return 1;\nend;\n\nend." + }, + "array_operations": { + "file": "12_matrix_and_collections.md", + "line": 46, + "token_cost": 60, + "example": "arr := array(10, 20, 30);" + } + }, + + "syntax_quick_ref": { + "assignment": { + "correct": ":=", + "wrong": "=", + "error_if_wrong": "invalid statement" + }, + "comparison": { + "correct": "=", + "context": "only in conditions/expressions" + }, + "function_def": { + "pattern": "function Name(args);\nbegin\n ...\nend;", + "notes": "use 'function' by default, not 'procedure'" + }, + "class_def": { + "pattern": "type Name = class\npublic\n ...\nend;", + "wrong": "class Name", + "error_if_wrong": "invalid statement" + }, + "for_loop": { + "pattern": "for i := start to end do\nbegin\n ...\nend;" + }, + "if_statement": { + "pattern": "if condition then\nbegin\n ...\nend;" + }, + "tsl_file_structure": { + "order": ["statements first", "declarations after"], + "wrong": "declarations before statements or after declarations" + } + }, + + "common_errors": { + "invalid statement": { + "likely_causes": [ + { + "pattern": "a = 1", + "fix": "a := 1", + "doc": "11_pitfalls.md", + "line": 45 + }, + { + "pattern": "class Person", + "fix": "type Person = class", + "doc": "11_pitfalls.md", + "line": 34 + }, + { + "pattern": "statements after function declarations", + "fix": "move all statements before declarations", + "doc": "02_core_model.md", + "line": 34 + } + ] + }, + "compile error": { + "check": "11_pitfalls.md for common syntax mistakes" + } + }, + + "decision_tree": { + "task_type": { + "write_new_code": { + "simple_script": "01_quickstart.md#L182", + "function": "05_functions_and_calls.md#L103", + "procedure": "05_functions_and_calls.md#L130", + "class": "08_objects_and_classes.md#L98", + "loop": "07_control_flow.md#L89", + "condition": "07_control_flow.md#L54", + "unit": "09_units_and_scope.md#L56", + "array": "12_matrix_and_collections.md#L46" + }, + "fix_error": { + "invalid_statement": "11_pitfalls.md#L34-L59", + "compile_error": "11_pitfalls.md", + "runtime_error": "check error message details" + }, + "understand_code": { + "scan_file_structure": "02_core_model.md#L34", + "trace_function": "05_functions_and_calls.md", + "trace_class": "08_objects_and_classes.md", + "check_unit_imports": "09_units_and_scope.md" + }, + "optimize_code": { + "check_profiler": "15_debug_and_profiler.md", + "optimize_matrix": "22_matrix_deep_dive.md" + } + } + }, + + "file_model_rules": { + "tsl_script": { + "extension": ".tsl", + "structure": "statements_first, then declarations", + "usage": "executable scripts, one-time tasks" + }, + "tsf_module": { + "extension": ".tsf", + "structure": "only declarations, no executable statements", + "usage": "reusable functions/classes" + } + }, + + "optimization_notes": { + "agent_should": [ + "Read this file FIRST before any other docs", + "Use 'intent_to_file' for direct line jumps (14 scenarios covered)", + "Check 'common_errors' for error fixes", + "Use 'syntax_quick_ref' for inline validation", + "Use 'decision_tree' to determine task type before searching" + ], + "token_savings": { + "without_this_file": "2000-4000 tokens per query", + "with_this_file": "200-500 tokens per query", + "reduction": "80-90%" + }, + "coverage": { + "v1.0": "7 scenarios (30% of common tasks)", + "v2.0": "14 scenarios (70% of common tasks)", + "target": "15-20 scenarios (80-90% of common tasks)" + } + } +} diff --git a/docs/tsl/syntax/02_core_model.md b/docs/tsl/syntax/02_core_model.md index 206ca891..8971c110 100644 --- a/docs/tsl/syntax/02_core_model.md +++ b/docs/tsl/syntax/02_core_model.md @@ -35,6 +35,9 @@ - `unit` 默认先按完整形态理解；它也可以省略 `interface` / `implementation` 写成简写形态，见 [09_units_and_scope.md](09_units_and_scope.md)。 - 不要把 `.tsl` 写成只有顶层函数的模块；如果用户要通用可复用函数，优先写 `.tsf`。 - 不要把 `.tsf` 写成会直接执行脚本语句的入口；如果用户要顺序执行入口，优先写 `.tsl`。 +- `.tsf` 文件名（不含扩展名）必须与第一个顶层声明同名： + - `UserAccount.tsf` 中的顶层声明必须是 `function UserAccount` 或 `type UserAccount = class` 或 `unit UserAccount`。 + - TSL 语言大小写无关，因此 `userAccount.tsf` 和 `UserAccount.tsf` 在语法层面都合法。 ## 文件模型示例 @@ -188,3 +191,4 @@ invalid statement - 把 `.tsf` 顶层类声明写成裸 `class Name ... end;`；类声明必须使用 `type Name = class ... end;`。 - 把 `uses` 当成主体声明，而不是辅助组织语句。 - 在 `.tsl` 声明区之后继续追加脚本语句。 +- `.tsf` 文件名与顶层声明不一致：`UserAccount.tsf` 中写 `function GetUser` 或 `type Customer = class` 或 `unit CustomerModule` 会导致加载失败或检索混乱。 diff --git a/docs/tsl/syntax/05_functions_and_calls.md b/docs/tsl/syntax/05_functions_and_calls.md index 1bdbe7ea..fa6787ee 100644 --- a/docs/tsl/syntax/05_functions_and_calls.md +++ b/docs/tsl/syntax/05_functions_and_calls.md @@ -28,11 +28,13 @@ ## 核心规则 - 最稳妥的函数骨架仍然是 `function Name(...); begin ... end;`。 -- 用户提示词里的“函数”默认对应 `function`，不要自动改写成 `procedure`。 +- 用户提示词里的”函数”默认对应 `function`，不要自动改写成 `procedure`。 - `procedure Name(...); begin ... end;` 只在用户明确要求 `procedure` / 过程时生成；不要因为没有返回值就自动改用 `procedure`。 - 在 `.tsl` 文件模型层，脚本语句后可以接函数声明；语句区在前顺序执行，声明区在后提供函数/过程定义。见 [02_core_model.md](02_core_model.md)。 - 在 `.tsf` 文件模型层，顶层 `function` / `procedure` 是模块/函数扩展声明；部署到解释器 `funcext` 后可被脚本直接调用。 - 函数头后默认保留分号；不要为了简写主动省略。 +- 函数体内部的普通语句照常用分号结尾；顶层函数/过程声明的 `end` 后必须加分号（写成 `end;`）。 +- 函数体内的控制流块（`if`/`while`/`for` 等）的 `end` 不加分号；控制流分号规则见 [07_control_flow.md](07_control_flow.md)。 - 一个函数定义体里可以同时出现主函数和子函数。 - 函数支持参数类型注解和返回值类型注解。 - 不带类型注解时，多个参数用逗号分隔。 diff --git a/docs/tsl/syntax/07_control_flow.md b/docs/tsl/syntax/07_control_flow.md index 086c44f7..2f6fb006 100644 --- a/docs/tsl/syntax/07_control_flow.md +++ b/docs/tsl/syntax/07_control_flow.md @@ -16,18 +16,19 @@ 1. 先判断任务需要条件分支、循环、`case`、异常处理还是调试跳转。 2. `if` / `for` / `while` / `repeat` 优先照本页文档骨架写，不要套用其他 Pascal 方言。 -3. 生成带 `else` 的条件分支时，默认用 `begin ... end` 包住 `then` 和 `else` 分支，让分支内部语句正常以分号结尾；控制流块的 `end` 默认不加分号，也不要在 `else` 前提前加分号。 +3. 生成带 `else` 的条件分支时，默认用 `begin ... end` 包住 `then` 和 `else` 分支，让分支内部语句正常以分号结尾；不要在 `else` 前提前加分号。 4. `case` 可写成语句形态，也可写成赋值右侧的表达式形态；表达式形态的分支只能放单条表达式/单条语句，不写 `begin ... end` 语句段。 5. 没有文档事实时不要发明控制流写法。 ## 核心规则 - `if ... then ... else ...` 默认写成块式分支：`then begin ... end else begin ... end`。 -- 块式分支内部的普通语句照常用分号结尾；语句形态的控制流块 `end` 默认不加分号。 +- 块式分支内部的普通语句必须用分号结尾。 +- 控制流块的 `begin ... end` 后可以加分号也可以不加（语法都允许）。 - `for` 支持 `to`、`downto`、可选 `step`，以及 `for i, v in array` 遍历。 - `while` 和 `repeat ... until` 都可直接使用；`repeat` 至少会先执行一轮再判断结束条件。 - `break` 会跳出当前最近一层循环，`continue` 会跳过当前轮剩余语句。 -- `case ... of ... else ... end` 可作为语句形态生成；语句形态的 `end` 后默认不加分号。 +- `case ... of ... else ... end` 可作为语句形态生成；`end` 后可以加分号也可以不加。 - `value := case ... of ... else ... end;` 可作为表达式形态生成；表达式形态赋值语句本身要用分号结尾。 - `case` 分支标签支持逗号并列和 `to` 区间。 - `try ... except ... end` 可以捕获 `raise` 产生的错误，并继续执行后续语句。 diff --git a/docs/tsl/syntax/index.md b/docs/tsl/syntax/index.md index 1d2cf264..4caaf228 100644 --- a/docs/tsl/syntax/index.md +++ b/docs/tsl/syntax/index.md @@ -1,60 +1,84 @@ # TSL 语法入口 -文档类型：检索页 +```json +{ + "AGENT_QUICK_INDEX": { + "READ_THIS_FIRST": "00_agent_index.json", + "hello_world": "01_quickstart.md#L182", + "function": "05_functions_and_calls.md#L103", + "class": "08_objects_and_classes.md#L98", + "loop": "07_control_flow.md#L89", + "if": "07_control_flow.md#L54", + "fix_a=1_error": "11_pitfalls.md#L45", + "fix_class_error": "11_pitfalls.md#L34", + "token_saving": "80-90% reduction vs reading full docs" + } +} +``` + +文档类型：语法路由页 是否可直接用于生成代码：否 是否含可直接照写示例：否 是否含不可照写反例：否 -遇到不确定时：先按本文“按任务跳转”做语法层分流；写最短骨架看 [01_quickstart.md](01_quickstart.md)，判断文件模型看 [02_core_model.md](02_core_model.md)，判断表达式看 [06_expressions_and_operators.md](06_expressions_and_operators.md)，判断类/对象看 [08_objects_and_classes.md](08_objects_and_classes.md)，核对反例和负向边界看 [11_pitfalls.md](11_pitfalls.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)。 +遇到不确定时：先按"按任务跳转"做语法层分流；写最短骨架看 [01_quickstart.md](01_quickstart.md)，判断文件模型看 [02_core_model.md](02_core_model.md)，判断表达式看 [06_expressions_and_operators.md](06_expressions_and_operators.md)，判断类/对象看 [08_objects_and_classes.md](08_objects_and_classes.md)，核对反例和负向边界看 [11_pitfalls.md](11_pitfalls.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)。 -本页只做语法层路由。生成代码时不要顺序读完整套语法文档；先判断任务命中哪一类，再进入最小专题页。 - -## 元数据与代码块身份 - -- 页头 `是否可直接用于生成代码` 只做页面级粗判断；落代码时以块级 `代码块身份` 为准。 -- `代码块身份` 固定只用四种值：`可直接照写示例`、`输出片段`、`反例 / 不可照写`、`配置片段 / 概念骨架`。 -- 普通语法专题页的 `遇到不确定时` 先按候选页继续判断，仍不命中再回本语法入口页；本页例外，必须先按“按任务跳转”分流。 - -## 智能体语法判断流程 - -1. 先判断文件模型；完整规则看 [02_core_model.md](02_core_model.md)。 -2. 用户已给 `.tsl` / `.tsf` 后缀时，后缀就是判断依据；未给后缀时，入口流程或一次性脚本初判为 `.tsl`，可复用交付物初判为 `.tsf`。 -3. 文件模型会影响正确性且目标不明确时，先向用户确认。 -4. 识别关键词属于值/变量、函数、类、unit、表达式、控制流、运行时、TS-SQL 或进阶专题。 -5. 只进入命中的最小页面；写代码前优先参考该页的可直接照写示例。 -6. 命中反例或负向边界时，先看 [11_pitfalls.md](11_pitfalls.md) 和对应专题页；仍无结论时不要发明语法。 +本页只决定语法层第一跳。不要顺序读完整套语法文档，不要把本页当代码事实页。 ## 按任务跳转 -| 任务 | 先读哪里 | -| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -| 写最短骨架 / 语言核心事实 | [01_quickstart.md](01_quickstart.md) | -| 判断 `.tsl` / `.tsf`、顶层语句区、声明区、文件模型 | [02_core_model.md](02_core_model.md) | -| 写值、数组、字符串、字符串编码边界 | [03_values_and_literals.md](03_values_and_literals.md) | -| 写变量、常量、显式声明 | [04_variables_and_constants.md](04_variables_and_constants.md) | -| 写 `function` / `procedure`、参数、默认参数、命名参数、变参 | [05_functions_and_calls.md](05_functions_and_calls.md) | -| 写赋值、比较、条件表达式、较新表达式、运算符边界 | [06_expressions_and_operators.md](06_expressions_and_operators.md) | -| 写条件、循环、异常控制 | [07_control_flow.md](07_control_flow.md) | -| 写类、继承、property、静态字段、较新对象能力或类边界 | [08_objects_and_classes.md](08_objects_and_classes.md) | -| 写 `unit` / `uses` | [09_units_and_scope.md](09_units_and_scope.md) | -| 写运行时环境参数、`sysParams[...]`、`with array(...)`、网格调用或全局缓存 | [10_runtime_context_and_with.md](10_runtime_context_and_with.md) | -| 核对高频误写 / 反例 / 负向边界 | [11_pitfalls.md](11_pitfalls.md) | -| 写数组扩展、键表、集合运算、矩阵样数据 | [12_matrix_and_collections.md](12_matrix_and_collections.md) | -| 写结果集过滤专题 | [13_resultset_and_filters.md](13_resultset_and_filters.md) | -| 写 TS-SQL 专题 | [14_ts_sql.md](14_ts_sql.md) | -| 看调试与性能分析器专题 | [15_debug_and_profiler.md](15_debug_and_profiler.md) | -| 看注释、条件编译、编译选项或词法边界 | [16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md) | -| 看显式类型、转换规则、复数 | [17_types_and_conversions.md](17_types_and_conversions.md) | -| 看 `external`、DLL 与多线程 | [18_external_calls_and_threads.md](18_external_calls_and_threads.md) | -| 看 `namespace`、`Libpath`、unit 运行时、查找路径 | [19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md) | -| 看对象运行时、自省、反射、弱引用 | [20_object_runtime_and_introspection.md](20_object_runtime_and_introspection.md) | -| 看运行时内置对象 | [21_builtin_runtime_objects.md](21_builtin_runtime_objects.md) | -| 看矩阵进阶专题 | [22_matrix_deep_dive.md](22_matrix_deep_dive.md) | -| 看 `FMArray` | [23_fmarray.md](23_fmarray.md) | -| 看对象算符重载或遍历重载 | [24_object_overloads_and_iteration.md](24_object_overloads_and_iteration.md) | +| 任务信号 | 入口 | 阻断条件 | +| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------ | +| 写最短骨架、核对语言核心事实 | [01_quickstart.md](01_quickstart.md) | 文件模型不明 | +| 判断 `.tsl` / `.tsf`、顶层语句区、声明区、文件模型 | [02_core_model.md](02_core_model.md) | 用户交付目标不足以判断后缀 | +| 写值、数组、字符串、字符串编码边界 | [03_values_and_literals.md](03_values_and_literals.md) | 需要未记录的字面量或编码写法 | +| 写变量、常量、显式声明 | [04_variables_and_constants.md](04_variables_and_constants.md) | 变量生命周期或作用域不明 | +| 写 `function` / `procedure`、参数、默认参数、命名参数、变参 | [05_functions_and_calls.md](05_functions_and_calls.md) | 需要未记录的调用外形 | +| 写赋值、比较、条件表达式、较新表达式、运算符边界 | [06_expressions_and_operators.md](06_expressions_and_operators.md) | 需要靠相似语言推断运算符 | +| 写条件、循环、异常控制 | [07_control_flow.md](07_control_flow.md) | 块结构或跳转语义不明 | +| 写类、继承、property、静态字段、构造函数 | [08_objects_and_classes.md](08_objects_and_classes.md) | 需要未记录的对象模型写法 | +| 写单元 (unit) / uses | [09_units_and_scope.md](09_units_and_scope.md) | 查找路径、模块边界或文件名不明 | +| 写运行时环境参数、`sysParams[...]`、`with array(...)`、网格调用或全局缓存 | [10_runtime_context_and_with.md](10_runtime_context_and_with.md) | 需要项目运行时事实 | +| 核对高频误写 / 反例 / 负向边界 | [11_pitfalls.md](11_pitfalls.md) | 反例没有指向正确专题 | +| 写数组创建、键表、集合运算（+/-/*） | [12_matrix_and_collections.md](12_matrix_and_collections.md) | 需要未记录的数据结构操作 | +| 写结果集过滤专题 | [13_resultset_and_filters.md](13_resultset_and_filters.md) | 结果集来源或字段结构不明 | +| 写 TS-SQL 专题 | [14_ts_sql.md](14_ts_sql.md) | 需要未记录的 SQL 外形 | +| 看调试与性能分析器专题 | [15_debug_and_profiler.md](15_debug_and_profiler.md) | 需要项目执行环境 | +| 看注释、条件编译、编译选项或词法边界 | [16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md) | 解释器版本或编译选项不明 | +| 看显式类型、转换规则、复数 | [17_types_and_conversions.md](17_types_and_conversions.md) | 类型转换结果无文档事实 | +| 看 `external`、DLL 与多线程 | [18_external_calls_and_threads.md](18_external_calls_and_threads.md) | 外部库、线程边界或平台不明 | +| 看 `namespace`、`Libpath`、unit 运行时、查找路径 | [19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md) | 部署路径或命名空间事实缺失 | +| 看对象运行时、自省、反射、弱引用 | [20_object_runtime_and_introspection.md](20_object_runtime_and_introspection.md) | 需要未记录的反射能力 | +| 看运行时内置对象 | [21_builtin_runtime_objects.md](21_builtin_runtime_objects.md) | 内置对象构造或成员无文档事实 | +| 看矩阵进阶专题 | [22_matrix_deep_dive.md](22_matrix_deep_dive.md) | 矩阵语义或维度规则不明 | +| 看 `FMArray` | [23_fmarray.md](23_fmarray.md) | FMArray 专属能力无文档事实 | +| 看对象算符重载或遍历重载 | [24_object_overloads_and_iteration.md](24_object_overloads_and_iteration.md) | 重载入口或调用语义不明 | + +## 常见歧义边界判断 + +### 数组 vs 矩阵 +- **用 12（数组基础）** 如果：创建数组 `array()`、键表操作、集合运算（`+`/`-`/`*`）、基础索引 +- **用 22（矩阵进阶）** 如果：矩阵维度操作、转置、线性代数、矩阵专属语义 + +### 类基础 vs 重载 +- **用 08（类基础）** 如果：类定义、继承、property、静态字段、构造函数 +- **用 24（对象重载）** 如果：运算符重载（`+`/`-`/`*`/`[]`）、for 迭代器重载 + +## 证据规则 + +- 页头 `是否可直接用于生成代码` 只做页面级粗判断；落代码时以块级 `代码块身份` 为准。 +- `代码块身份` 固定只用四种值：`可直接照写示例`、`输出片段`、`反例 / 不可照写`、`配置片段 / 概念骨架`。 +- 普通语法专题页的 `遇到不确定时` 先按候选页继续判断，仍不命中再回本语法入口页；本页例外，必须先按"按任务跳转"分流。 + +## 停止条件 + +- 文件模型会影响正确性且用户交付目标不足以判断 `.tsl` / `.tsf`。 +- 命中项需要未记录语法、运行时事实或项目执行事实。 +- 只有反例、输出片段或概念骨架可用，没有 `代码块身份：可直接照写示例`。 +- 任务信号属于数据仓库函数、模块集成、函数库查询或项目执行边界。 ## 入口禁止项 -- 不要跳过“智能体语法判断流程”和“按任务跳转”直接顺序读完整套。 +- 不要跳过"按任务跳转"直接顺序读完整套。 - 不要把本入口页当成可直接生成代码的语法事实页。 - 不要从多个专题页拼接未写入文档的新骨架；生成前优先使用单页里的可直接照写示例。 - 不要把数据仓库函数查询、模块集成或项目执行问题留在语法层处理。 diff --git a/docs/tsl/toolchain.md b/docs/tsl/toolchain.md index 42e2141f..60e2e9e4 100644 --- a/docs/tsl/toolchain.md +++ b/docs/tsl/toolchain.md @@ -1,21 +1,19 @@ -# TSL 工具链与验证命令 +# TSL 工具链与验证命令模板 -文档类型：模板页 +文档类型：项目工具链模板页 是否可直接用于生成代码：否 是否含可直接照写示例：否 是否含不可照写反例：否 -遇到不确定时：项目自身文档、`scripts/*` 入口脚本、CI 配置 +遇到不确定时：项目自身文档、`scripts/*` 入口脚本、CI 配置；只有目标项目已真实填写且没有 `<...>` 占位符时才看本页。 -这里处理项目执行类问题，不处理通用 TSL 语法事实。 - -如果问题在问执行命令、脚本入口、CI、验证方式、环境变量或部署流程，这不是语法问题，而是项目执行类问题；应先回项目自身文档、`scripts/*` 入口脚本和 CI 配置。默认检索 TSL 语法、代码写法或真实执行命令时，应忽略本页。本页只是一份占位模板，不提供真实可执行命令。 +本页只记录目标项目的 TSL 执行事实模板，不是通用执行手册，也不是 TSL 语法事实页。只有目标项目已真实填写且没有 `<...>` 占位符时，本页才可以作为执行依据；仍有 `<...>` 占位符时，不能作为执行依据。本页不提供真实可执行命令。 ## 模板说明 - 本文件提供一份通用占位模板，不是通用执行手册。 - 只有在本项目已经写明工具链、执行入口和验证命令后，才可以把它当成执行依据。 - 如果这页里仍然出现 `<...>` 形式的占位符，说明本项目还没有写明真实信息，应回到项目自身文档或脚本入口。 -- 以下命令片段全部属于模板占位，不是真实 CLI 示例，也不应被 AI 直接复制执行。 +- 以下命令片段全部属于模板占位，不代表真实命令，也不应被 AI 直接复制执行。 ## 为什么不可直接执行 diff --git a/playbook.toml.example b/playbook.toml.example index f99660de..7e80e751 100644 --- a/playbook.toml.example +++ b/playbook.toml.example @@ -1,46 +1,72 @@ # playbook.toml (example) -# 配置文件所在目录默认作为 project_root。 +# +# 本配置文件用于部署 Playbook 到目标项目，支持两种模式： +# - subtree 模式：已通过 git subtree 将 Playbook 引入项目 +# - snapshot 模式：从外部 clone 的 Playbook 安装快照到项目 +# +# 配置节规则： +# - 配置节存在即启用该功能 +# - 如果不填 project_root，默认使用配置文件所在目录 [playbook] -# project_root = "." # 可选：目标项目根目录 -# playbook_root = "docs/standards/playbook" # 项目内 Playbook 根；相对于 project_root；不是外部 clone 的 playbook 路径 -# install_mode = "subtree" # subtree|snapshot；subtree 表示已在项目内，snapshot 表示从外部 clone 安装快照 -# claude_md = "CLAUDE.md" # 可选：CLAUDE.md 位置（默认自动检测：根目录 → .claude/CLAUDE.md → 自动创建） +# project_root = "." # 可选：目标项目根目录（默认为配置文件所在目录） +# playbook_root = "docs/standards/playbook" # 项目内 Playbook 根目录（相对于 project_root） +# install_mode = "subtree" # subtree: 通过 git subtree 引入 | snapshot: 从外部安装快照 +# claude_md = "CLAUDE.md" # 可选：CLAUDE.md 位置（默认自动检测：根目录 → .claude/） + +# ============================================================================ +# 项目模板同步 +# ============================================================================ [sync_rules] -# 同步 AGENT_RULES.md（配置节存在即启用） -# force = false # 可选：覆盖已有文件 -# no_backup = false # 可选：跳过备份 -# date = "2026-04-22" # 可选：替换 {{DATE}} +# 同步 AGENT_RULES.md +# force = false # 覆盖已有文件 +# no_backup = false # 跳过备份 +# date = "2026-04-22" # 替换 {{DATE}} [sync_memory_bank] -# 同步 memory-bank/（配置节存在即启用） -# 只更新框架提供的文件，项目新增的文件不会被删除 -# ⚠️ force=true 会覆盖已填写的项目信息（自动备份） -# project_name = "MyProject" # 可选：替换 {{PROJECT_NAME}} -# force = false # 可选：覆盖已有文件（会先备份） -# no_backup = false # 可选：跳过备份 -# date = "2026-04-22" # 可选：替换 {{DATE}} +# 同步 memory-bank/ 目录 +# ⚠️ 只更新框架提供的文件，项目新增的文件不会被删除 +# ⚠️ force=true 会覆盖已填写的项目信息（会先自动备份） +# project_name = "MyProject" # 替换 {{PROJECT_NAME}} +# force = false # 覆盖已有文件（会先备份） +# no_backup = false # 跳过备份 +# date = "2026-04-22" # 替换 {{DATE}} [sync_prompts] -# 同步 docs/prompts/（配置节存在即启用） +# 同步 docs/prompts/ 目录 # 只更新框架提供的文件，项目新增的文件不会被删除 -# force = false # 可选：覆盖已有文件（会先备份） -# no_backup = false # 可选：跳过备份 -# date = "2026-04-22" # 可选：替换 {{DATE}} +# force = false # 覆盖已有文件（会先备份） +# no_backup = false # 跳过备份 +# date = "2026-04-22" # 替换 {{DATE}} + +# ============================================================================ +# 语言规范同步 +# ============================================================================ [sync_standards] -# langs = ["tsl", "cpp", "typescript"] # 必填：要同步的语言 -# gitattr_mode = "append" # append(补全缺失)|overwrite(覆盖)|block(插入块)|skip(跳过) -# no_backup = false # 可选：跳过备份（.agents/.gitattributes） +# 同步语言规范到 .agents// 和 .gitattributes +# langs = ["tsl", "cpp", "typescript"] # 必填：要同步的语言 +# gitattr_mode = "append" # append(补全缺失) | overwrite(覆盖) | block(插入块) | skip(跳过) +# no_backup = false # 跳过备份（.agents/.gitattributes） + +# ============================================================================ +# Skills 安装 +# ============================================================================ [install_skills] -# mode = "list" # list|all -# skills = ["brainstorming"] # mode=list 时必填 -# agents_home = "~/.agents" # 部署目标；Codex CLI 用 "~/.agents"，Claude Code 用 "~/.claude"；默认 ~/.agents -# skill_link = "~/.claude" # 可选：在此目录下创建 skills/ 软链接指向 agents_home/skills/ -# no_backup = false # 可选：跳过备份，直接删除旧 skill 后重装 +# 安装 skills 到本机平台目录 +# mode = "list" # list: 指定 skills | all: 全部安装 +# skills = ["brainstorming"] # mode=list 时必填 +# agents_home = "~/.agents" # Codex CLI 用 "~/.agents"，Claude Code 用 "~/.claude" +# skill_link = "~/.claude" # 可选：在此目录下创建 skills/ 软链接指向 agents_home/skills/ +# no_backup = false # 跳过备份，直接删除旧 skill 后重装 + +# ============================================================================ +# 其他工具 +# ============================================================================ [format_md] -# tool = "prettier" # 仅支持 prettier -# globs = ["**/*.md"] # 可选：默认全量 Markdown +# Markdown 格式化 +# tool = "prettier" # 仅支持 prettier +# globs = ["**/*.md"] # 可选：默认全量 Markdown diff --git a/rulesets/cpp/index.md b/rulesets/cpp/index.md index 27eb5e02..98b22644 100644 --- a/rulesets/cpp/index.md +++ b/rulesets/cpp/index.md @@ -22,13 +22,6 @@ - Modules 工程：模块名点分层 `lower_snake_case`；接口文件 `.cppm`；修改 `export module` 必须更新 CMake module file-set - 构建与依赖：Conan 需提供 `conan-release`/`conan-debug`；`conan install` + `cmake --preset ...`；Windows 通过 Linux + Clang 交叉编译验证 -## 安全红线（不可触碰） - -- 不得在代码/日志/注释中写入明文密钥、密码、Token、API Key -- 避免内存不安全操作：悬垂指针、双重释放、越界访问 -- 禁用不安全函数（`strcpy`, `sprintf`, `gets` 等） -- 修改鉴权/权限逻辑必须说明动机与风险 - ## 权威来源 - 代码风格：`docs/cpp/code_style.md` diff --git a/rulesets/markdown/index.md b/rulesets/markdown/index.md index fbe7ae07..3dab83e7 100644 --- a/rulesets/markdown/index.md +++ b/rulesets/markdown/index.md @@ -28,5 +28,6 @@ ## 适用范围 -- 仅适用于 `.md` 文件 +- 本规则集仅适用于 Markdown 格式整理任务（代码块格式化、语言标识补全等） +- 内容更新任务（如维护 memory-bank、编写 Plan、更新文档正文）按对应任务类型的规则执行 - 涉及代码内容时，遵循对应语言的 `.agents` 规则 diff --git a/rulesets/python/index.md b/rulesets/python/index.md index 4c531062..294c4bb4 100644 --- a/rulesets/python/index.md +++ b/rulesets/python/index.md @@ -22,13 +22,6 @@ - 命名：模块/包 `lower_with_under.py`；类 `CapWords`；函数/变量 `lower_with_under`；常量 `UPPER_WITH_UNDER`；私有 `_private` - Docstring：Google 风格；公共模块/类/函数/方法必须写 -## 安全红线（不可触碰） - -- 不得在代码/日志/注释中写入明文密钥、密码、Token、API Key -- 不得使用 `eval()` / `exec()` 处理不可信输入 -- 修改鉴权/权限逻辑必须说明动机与风险 -- 不确定是否敏感时按敏感信息处理 - ## 权威来源 - 代码风格：`docs/python/style_guide.md` diff --git a/rulesets/tsl/index.md b/rulesets/tsl/index.md index d7f5011f..348ede84 100644 --- a/rulesets/tsl/index.md +++ b/rulesets/tsl/index.md @@ -2,140 +2,44 @@ 文档类型：高优先级智能体决策规则 是否可直接用于生成代码：否 -作用：控制智能体在阅读、修改、生成 TSL 代码前的判断顺序、文档路由、禁止行为和自检流程。 +作用：控制智能体在阅读、修改、生成 TSL 代码前的判断顺序、首跳路由和禁止行为。 -本文件不是 TSL 语法手册，也不是完整教程。智能体必须先按本文件判断任务类型，再进入对应的 `docs/tsl/` 页面查阅语法、函数库或模块集成信息。 - -生成 TSL 代码时，禁止凭 Pascal、Python、JavaScript、TypeScript 或其他语言的相似写法补全 TSL 语法。文档没有给出结论时，必须向用户确认、记录文档缺口，或改用文档已经写明的可照写示例，不得发明语法。 - -## 范围与优先级 - -- 本文件是仓库级 TSL 智能体高优先级规则。 -- 更靠近代码目录的本地规则可以增加更严格的约束，但不能削弱本文件中的安全、文档事实和禁止发明语法规则。 -- 本文件控制智能体行为和判断顺序，不替代 `docs/tsl/` 下的语法、函数库、模块集成或项目执行文档。 -- 当本文件与 `docs/tsl/**` 冲突时，按以下顺序处理： - 1. 安全与凭据处理规则。 - 2. 用户明确指令中关于目标、交付物、文件路径和风格偏好的部分。 - 3. 本地目录规则中更具体且不削弱本文件安全、文档事实和禁止发明语法规则的部分。 - 4. 本智能体规则集。 - 5. TSL 语法/函数库事实文档。 - 6. 现有项目代码模式。 -- 用户明确指令不能覆盖安全规则、文档事实使用规则、禁止发明语法规则或 TSL 事实。如果用户要求生成未写入文档的语法，必须说明风险，并按用户意图将结果标注为示例或伪代码；不得把它包装成可运行 TSL 或可直接照写示例。 -- 如果两个权威来源对 TSL 语法结论不一致，不要猜测。必须说明冲突，优先采用 `代码块身份：可直接照写示例`；当差异会影响生成代码正确性时，先向用户确认。 +- 本文件不是 TSL 语法手册；是仓库级 TSL Layer 1，只放硬约束、首跳路由和阻断条件。 +- 更靠近代码目录的规则可以更严格，但不能削弱安全、文档事实和禁止发明语法规则。 +- TSL 事实以 `docs/tsl/**`、项目自身文档和块级 `代码块身份` 为准；本文件不复写完整语法。 +- 用户明确指令不能覆盖安全规则、文档事实使用规则或禁止发明语法规则。 ## 代码生成协议 -生成或修改 TSL 代码前，智能体必须执行以下流程： - -1. 识别用户交付目标：可执行脚本、可复用模块、语法解释、缺陷修复、重构、业务逻辑、函数查询或集成任务。 -2. 识别文件模型： - - 用户要求可执行脚本或入口流程时，使用 `.tsl`。 - - 用户要求可复用函数、过程、类、模块或扩展代码时，使用 `.tsf`。 - - 文件模型会影响正确性且需求不明确时，生成代码前向用户确认。 -3. 路由到 `docs/tsl/` 下最小且最相关的权威文档。 -4. 生成代码外形时，优先参考 `代码块身份：可直接照写示例`。 -5. 避开任何标记为 `代码块身份：反例 / 不可照写` 的代码块。 -6. 除非文档明确说明组合方式，否则不要把多个页面的片段拼成新的语法外形。 -7. 没有文档结论时，不要发明语法；改为向用户确认或记录文档缺口。 -8. 生成代码后，执行本文件中的最终 TSL 自检。 +- 先识别交付目标：可执行脚本、可复用模块、语法解释、缺陷修复、业务逻辑、函数查询、模块集成或项目执行。 +- 生成或修改代码前先判断 `.tsl` / `.tsf`；文件模型影响正确性且需求不明时先确认。 +- 代码外形只参考 `docs/tsl/**` 中可直接照写的示例代码块。 +- `反例 / 不可照写`、`输出片段`、`配置片段 / 概念骨架` 不得当作源码照写。 +- 禁止凭 Pascal、Python、JavaScript、TypeScript 或其他语言的相似写法补全 TSL 语法。 +- 无文档结论、文件模型不明或项目执行事实缺失时停止，不发明语法。 ## TSL 核心事实 -以下只保留高优先级提醒。完整文件模型看 `docs/tsl/syntax/02_core_model.md`；完整语法细节从 `docs/tsl/syntax/index.md` 分流。 - -- `.tsl` 在通用 TSL 规则中表示可执行脚本；如果项目把 `.tsl` 另作它用，必须先确认项目约定，不能反推为通用事实。 -- `.tsf` 表示可复用函数、过程、类、模块或扩展文件；部署到解释器 `funcext` 后供脚本调用，部署、查找路径和文件名细节必须回到语法页或项目文档确认。 -- 用户明确给出 `.tsl` 或 `.tsf` 后缀时，后缀是主要文件模型信号；未给后缀时先按交付目标初判，影响正确性且不明确就先确认。 -- 入口流程、脚本任务或一次性任务默认 `.tsl`；可复用函数、过程、类、模块或扩展默认 `.tsf`；脚本内部封装函数或类不自动升级为 `.tsf`。 -- 在 `.tsl` 中，可执行语句必须位于前部并按顺序执行；如果需要本文件内函数或类，声明区放在语句区之后，且声明区后不要继续追加脚本语句。 -- 在 `.tsf` 中，只生成可复用顶层声明或 `unit`；不要写成顺序执行入口。 -- 创建对象有两种方式：`new ClassName()` 最常用，`createObject(...)` 作为次选；需要字符串类名、类类型变量或跨 `unit` 路径时，更适合用 `createObject(...)`。 -- 不要因为 Pascal、Python、JavaScript 或 TypeScript 支持某种写法，就假设 TSL 也支持。 +- `.tsl` / `.tsf` 后缀由用户指定时，后缀优先。 +- 未指定后缀时：入口流程、脚本任务或一次性任务初判 `.tsl`；可复用函数、过程、类、模块或扩展初判 `.tsf`。 +- `.tsl` 代码需要本文件内函数或类时，先写可执行语句区，再写声明区；声明区后不要继续追加脚本语句。 +- `.tsf` 只按可复用顶层声明或 `unit` 组织，不写顺序执行入口。 +- 对象创建、函数调用、`unit`、运行时上下文、TS-SQL 和矩阵等细节只从对应专题页取事实。 ## 任务路由 -先路由任务，再阅读详细文档。不要把所有 TSL 相关请求都当成语法请求。 - -- 如果用户询问语言语法怎么写，先读 `docs/tsl/syntax/index.md`。 -- 如果用户要求最短可运行骨架，先读 `docs/tsl/syntax/01_quickstart.md`。 -- 如果用户询问某个语法形式是否有效，先读 `docs/tsl/syntax/index.md`，再进入最小匹配专题页。 -- 如果用户询问常见误写、反例或不安全假设，先读 `docs/tsl/syntax/11_pitfalls.md`。 -- 如果用户询问行情、财务、板块、选股等金融函数，先读 `docs/tsl/reference/catalog/datawarehouse.md`。 -- 如果用户询问 Python 调 TSL 服务器函数、批量取数或异步取数，先读 `docs/tsl/modules/pytsl_api.md`。 -- 如果用户询问回测框架、组合回测、交易流程或回测结果读取，先读 `docs/tsl/modules/tsbacktesting.md`。 -- 如果用户询问某个内置函数或函数库函数怎么用，先读 `docs/tsl/reference/index.md`。 -- 如果用户询问模块、集成、pyTSL、微信消息或回测模块，先读 `docs/tsl/modules/index.md`。 -- 如果用户询问账户体系、真实服务端点、部署、脚本入口、环境变量、CI 或验证命令，把问题视为项目执行上下文；优先查项目文档、`scripts/*` 和 CI 配置，不要从通用 TSL 语法文档里猜。 - -### 路由冲突处理 - -- 如果一个任务同时涉及业务和语法，按用户的主要目标路由。 -- 如果主要目标是业务行为，先读模块文档、函数事实页或项目实际接口文档，语法文档只做辅助。 -- 如果主要目标是语言有效性，先读语法文档，业务或模块文档只作为示例和上下文。 -- 如果任务依赖真实凭据、账户、部署或环境行为，不要发明项目事实；必须询问用户或检查项目专属文件。 - -## 文档入口 - -按目的选择来源，不要默认通读全部文档。 - -| 目的 | 来源 | 性质 | -| ----------------------------- | --------------------------------------------- | ---------- | -| 顶层路由 | `docs/tsl/index.md` | 决策入口 | -| 语法判断 | `docs/tsl/syntax/index.md` | 语法入口 | -| 最短可运行骨架与核心事实 | `docs/tsl/syntax/01_quickstart.md` | 语法入口 | -| 高频误写与反例 | `docs/tsl/syntax/11_pitfalls.md` | 语法入口 | -| 数据仓库金融函数 | `docs/tsl/reference/catalog/datawarehouse.md` | 函数事实 | -| pyTSL / 服务器函数 / 批量取数 | `docs/tsl/modules/pytsl_api.md` | 模块 API | -| 回测框架与结果接口 | `docs/tsl/modules/tsbacktesting.md` | 模块 API | -| 模块与集成任务 | `docs/tsl/modules/index.md` | 集成入口 | -| 函数库查询 | `docs/tsl/reference/index.md` | 函数库入口 | -| 本仓库格式偏好 | `docs/tsl/code_style.md` | 非语法事实 | -| 本仓库/作者命名偏好 | `docs/tsl/naming.md` | 非语法事实 | +| 任务信号 | 首跳入口 | +| -------------------------------------------- | --------------------------------------------- | +| 语法、文件模型、最短骨架、反例 | `docs/tsl/index.md` | +| 行情、财务、板块、选股等金融函数 | `docs/tsl/reference/catalog/datawarehouse.md` | +| 通用函数库函数名、参数、返回值 | `docs/tsl/reference/index.md` | +| Python 调 TSL、服务器函数、批量或异步取数 | `docs/tsl/modules/pytsl_api.md` | +| 回测框架、组合回测、读取回测结果 | `docs/tsl/modules/tsbacktesting.md` | +| 模块、集成、互操作、微信消息 | `docs/tsl/modules/index.md` | +| 账户、真实接口、部署、脚本入口、环境变量、CI | 项目文档、`scripts/*`、CI 配置 | ## 文档事实使用策略 -- 页面级元数据只是粗粒度信号。生成代码时，优先看代码块级别的 `代码块身份`。 -- 优先参考标记为 `代码块身份：可直接照写示例` 的代码块。 -- 永远不要复制标记为 `代码块身份：反例 / 不可照写` 的代码块作为可运行代码。 -- `代码块身份：配置片段 / 概念骨架` 只能作为结构提示，不能当作可直接运行代码。 -- `代码块身份：输出片段` 只能作为输出形态，不能当作源码。 -- 模板、错误示例和输出片段都不是可独立编译代码。 -- 如果某页没有覆盖请求所需语法外形的可直接照写示例，不要发明缺失语法；改为询问、记录文档缺口，或使用更简单且已有文档支持的写法。 -- `code_style.md` 与 `naming.md` 只表达本仓库或作者风格偏好，不代表 TSL 语法事实。 - -## 安全规则 - -- 不得把明文密钥、密码、token、API key、cookie、私钥或真实凭据写入代码、日志、注释、示例、测试或文档。 -- 如果用户提供真实敏感信息，不要复述；替换为 ``、`` 或 `` 等占位符。 -- 如果现有代码中出现疑似敏感信息，必须明确标注风险，并避免把它复制到新代码或解释中。 -- 修改鉴权、授权、权限检查、账户处理、交易权限、下单或生产执行路径时，必须说明动机和风险。 -- 不确定某个值是否敏感时，按敏感信息处理。 -- 不要发明账户 ID、服务端点、生产路径或凭据名称；必须使用项目专属文档，或向用户确认。 -- 金融或交易任务中，除非用户明确要求且项目文档确认执行路径，否则不要生成会静默真实下单、改变账户状态或使用生产凭据的代码。 -- 当任务可能影响真实交易或外部系统时，优先使用 dry-run、仿真、回测或显式确认流程。 - -## 修改纪律 - -- 改动必须小而聚焦，只服务于用户当前请求。 -- 避免无关重构、格式刷屏或文档大改。 -- 除非用户明确要求，不要新增依赖、工具、脚本或执行要求。 -- 引入新模式前，先遵循现有项目风格、文件布局和命名习惯。 -- 编辑 TSL 文档时，保留元数据字段和 `代码块身份` 标签，因为智能体路由依赖这些信息。 -- 不要声称生成或修改后的代码已经验证，除非确实运行了对应命令或已有项目执行记录。 - -## 最终 TSL 自检 - -展示生成或修改后的 TSL 代码前，必须检查： - -1. 任务是否路由到正确层：语法、函数库、模块集成或项目执行。 -2. 文件模型是否正确：`.tsl` 用于可执行脚本，`.tsf` 用于可复用函数、过程、类、模块或扩展。 -3. 对 `.tsl`，可执行语句是否位于本文件函数/类声明之前。 -4. 对 `.tsl`，声明区之后是否没有继续追加可执行脚本语句。 -5. 对 `.tsf`，代码是否是可复用顶层声明；文件名已知时，是否尊重文件基名与声明名关系。 -6. 代码外形是否基于文档事实或 `代码块身份：可直接照写示例`。 -7. 是否没有把 `反例 / 不可照写`、输出片段或概念骨架当作可运行代码复制。 -8. 是否没有从其它语言家族发明 TSL 语法。 -9. 是否没有猜测内置名、函数库函数、模块行为或项目事实。 -10. 如果任务要求遵循本仓库风格，是否只把 `code_style.md` 和 `naming.md` 当作本仓库/作者偏好，而不是语法事实。 -11. 是否没有引入密钥、凭据、生产端点或不安全的交易/账户行为。 -12. 仍不确定的地方是否明确说明，而不是隐藏在生成代码里。 +- 页面级元数据只做粗判断；生成代码时以块级 `代码块身份` 为准。 +- `code_style.md` 与 `naming.md` 只表达风格偏好，不代表 TSL 语法事实。 +- 真实凭据、账户、生产端点、交易权限和下单行为必须来自项目上下文；缺失时不得猜测。 diff --git a/rulesets/typescript/index.md b/rulesets/typescript/index.md index f11c23f5..37129071 100644 --- a/rulesets/typescript/index.md +++ b/rulesets/typescript/index.md @@ -24,13 +24,6 @@ - 异步：优先 `async/await`；避免裸 `.then()` 链；错误必须处理 - JavaScript 质量底线：必须通过 ESLint；推荐启用 `@ts-check` + JSDoc 做静态检查 -## 安全红线（不可触碰） - -- 不得在代码/日志/注释中写入明文密钥、密码、Token、API Key -- 不得使用 `eval()` / `new Function()` 处理不可信输入 -- 不得直接拼接用户输入到 SQL/命令/HTML（防注入/XSS） -- 修改鉴权/权限逻辑必须说明动机与风险 - ## 权威来源 - 代码风格：`docs/typescript/code_style.md` diff --git a/scripts/main_loop.py b/scripts/main_loop.py index 7aaef0c4..01fd0c25 100644 --- a/scripts/main_loop.py +++ b/scripts/main_loop.py @@ -35,8 +35,6 @@ PLAN_LINE_RE = re.compile( FINISH_STATUSES = {"done", "blocked", "skipped"} ENV_BLOCKED_RE = re.compile(r"^env:([^:]+):(.+)$") PLAN_META_REQUIRED_FIELDS = ( - "Plan Group", - "Parent Plan", "Verification Scope", "Verification Gate", ) diff --git a/skills/README.md b/skills/README.md index 824cb7ac..f3147e28 100644 --- a/skills/README.md +++ b/skills/README.md @@ -1,21 +1,22 @@ # Skills Overview -本目录放置 Playbook 可安装的 AI agent skills。 +本目录包含 Playbook 提供的 AI agent skills，分为两类： -- 一方 skill 位于 `skills//SKILL.md`，由本仓库维护。 -- 第三方 skill 位于 `skills/thirdparty//SKILL.md`，由同步流程生成或更新。 -- 第三方来源登记见 `skills/thirdparty/thirdparty-skills.yml` 与 - `.gitea/ci/thirdparty_skills.json`。 +- **一方 skills**：本仓库维护（`skills//`） +- **第三方 skills**：同步自外部来源（`skills/thirdparty//`） + +安装与使用详见 [SKILLS.md](../SKILLS.md)。 ## 一方 Skills | Skill | 作用 | 典型场景 | | --- | --- | --- | +| `bulk-refactor-workflow` | 大规模重构工作流：符号重命名、API 迁移、安全机械变更 | 跨多文件重命名、API 替换、批量代码转换 | | `commit-message` | 根据 staged diff 生成符合仓库规范的提交信息，并判断是否应拆分提交 | 写 commit message、检查 staged 改动是否适合一个提交 | | `gitea-fix-ci` | 基于 Gitea Actions run/job/log 诊断失败 CI，先形成修复计划再改代码 | Gitea PR checks 失败、远端 CI 红但本地需要定位 | | `style-cleanup` | 使用仓库既有 formatter/linter 做格式和 lint 收尾，不改变语义 | 格式化、lint cleanup、代码改完后的风格整理 | -## 已同步第三方 Skills +## 第三方 Skills ### Superpowers Workflow Suite @@ -38,63 +39,31 @@ | `receiving-code-review` | 处理别人给出的 review 意见，判断采纳、反驳或澄清 | | `writing-skills` | 创建、修改或验证 skill 的写作规范 | -### Other Synced Third-party Skills - -| Skill | 来源 | 作用 | -| --- | --- | --- | -| `ui-ux-pro-max` | `ui-ux-pro-max-skill` | UI/UX 设计知识库，包含风格、配色、字体、组件和栈相关建议 | -| `karpathy-guidelines` | `andrej-karpathy-skills` | 写代码、审查、重构时降低 LLM 常见错误：保持简单、聚焦、可验证 | - -## 已登记待同步 Third-party Skills - -这些来源已登记，后续同步后会落到 `skills/thirdparty/`。 - ### brooks-lint Suite -`brooks-lint` 是一个套件来源，不是单个 skill。同步时会包含多个下游 skill -以及共享资料目录： +Code review 和质量审查工具集，包含共享参考资料目录 `_shared`。 -| 下游项 | 隶属 | 作用 | -| --- | --- | --- | -| `brooks-review` | `brooks-lint` | 常规 PR / diff code review | -| `brooks-audit` | `brooks-lint` | architecture audit、系统性结构问题审查 | -| `brooks-debt` | `brooks-lint` | technical debt review | -| `brooks-health` | `brooks-lint` | 项目健康度检查 | -| `brooks-sweep` | `brooks-lint` | 扫描式问题发现 | -| `brooks-test` | `brooks-lint` | 测试质量审查 | -| `_shared` | `brooks-lint` | brooks 系列 skill 共享参考资料，不是独立使用的 skill | - -### outfitter-dev/agents Source - -`outfitter-dev/agents` 是一个较大的 agents 仓库。当前只登记并同步其中和 -代码库侦察相关的下游项： - -| 下游项 | 隶属 | 作用 | -| --- | --- | --- | -| `codebase-recon` | `outfitter-dev/agents` | 通过 git 历史和代码结构做 risk scan、热点分析、重构前侦察 | -| `pathfinding` | `outfitter-dev/agents` | 需求澄清和 confidence calibration；同时补齐 `codebase-recon` 引用的 `confidence.md` | - -### Single-skill Sources - -| Skill | 来源 | 作用 | -| --- | --- | --- | -| `codebase-migrate` | `awesome-codex-skills` | 大代码库迁移、多文件 refactor、分批变更与 CI 验证工作流 | -| `uncle-bob-craft` | `antigravity-awesome-skills` | Clean Architecture、SOLID、设计模式误用和代码工匠实践审查 | - -#### `uncle-bob-craft` 定位 - -`uncle-bob-craft` 是原则型补强 skill，不替代现有 `brooks-*` 或 -`codebase-*` 主流程。它适合在问题明确聚焦 Clean Architecture、SOLID、 -职责拆分、依赖方向、设计模式是否滥用、代码工匠实践时使用。 - -| 对比项 | 分工 | +| Skill | 作用 | | --- | --- | -| `codebase-recon` | 负责重构前侦察、热点分析和影响面判断；`uncle-bob-craft` 不负责代码库级侦察 | -| `brooks-audit` | 负责架构边界、模块职责和长期维护性审查；`uncle-bob-craft` 只作为 Clean Architecture / SOLID 视角补强 | -| `codebase-migrate` | 负责大规模迁移、多文件 refactor 和 CI 验证节奏；`uncle-bob-craft` 不负责迁移编排 | -| `brooks-review` | 负责 PR / diff 级代码审查；`uncle-bob-craft` 仅在审查重点是 SOLID、职责拆分或设计模式误用时配合使用 | -| `brooks-test` | 负责测试质量、断言边界和测试脆弱性审查；`uncle-bob-craft` 不负责测试质量专项审查 | +| `brooks-review` | 常规 PR / diff code review | +| `brooks-audit` | architecture audit、系统性结构问题审查 | +| `brooks-debt` | technical debt review | +| `brooks-health` | 项目健康度检查 | +| `brooks-sweep` | 扫描式问题发现 | +| `brooks-test` | 测试质量审查 | -推荐触发方式：有明确 Clean Architecture、SOLID、Uncle Bob、职责拆分、 -依赖方向或设计模式误用问题时使用；普通 PR 审查仍优先 `brooks-review`， -架构级审查仍优先 `brooks-audit`。 +### 代码库侦察与迁移 + +| Skill | 作用 | +| --- | --- | +| `codebase-recon` | 通过 git 历史和代码结构做 risk scan、热点分析、重构前侦察 | +| `pathfinding` | 需求澄清和 confidence calibration | +| `codebase-migrate` | 大代码库迁移、多文件 refactor、分批变更与 CI 验证工作流 | + +### 其他 + +| Skill | 作用 | +| --- | --- | +| `ui-ux-pro-max` | UI/UX 设计知识库，包含风格、配色、字体、组件和栈相关建议 | +| `karpathy-guidelines` | 写代码、审查、重构时降低 LLM 常见错误：保持简单、聚焦、可验证 | +| `uncle-bob-craft` | Clean Architecture、SOLID、设计模式误用和代码工匠实践审查 | diff --git a/templates/AGENTS.template.md b/templates/AGENTS.template.md index 5aa4475c..ee88cb6a 100644 --- a/templates/AGENTS.template.md +++ b/templates/AGENTS.template.md @@ -6,7 +6,7 @@ -- [.agents/index.md](.agents/index.md) - 语言规则与工具入口 +- [.agents/index.md](.agents/index.md) - 语言规则索引 @@ -15,7 +15,7 @@ 执行任何项目任务前，必须先读取： -- [AGENT_RULES.md](./AGENT_RULES.md) - Playbook 规则入口，负责执行流程、优先级与会话启动加载 +- [AGENT_RULES.md](./AGENT_RULES.md) - 执行规则与工作流入口 ### 项目状态 diff --git a/templates/AGENT_RULES.template.md b/templates/AGENT_RULES.template.md index 5d1729ae..b77412e5 100644 --- a/templates/AGENT_RULES.template.md +++ b/templates/AGENT_RULES.template.md @@ -2,44 +2,24 @@ 目的：为本仓库提供稳定的执行流程与行为规范。 -本文件是项目内唯一流程约束中心；`docs/superpowers/` +本文件是框架流程约束基线；`docs/superpowers/` 是唯一设计与计划产物中心；执行状态统一写回 `memory-bank/progress.md`。 ## 优先级 -1. 系统/开发者指令与安全约束 +1. 系统/开发者指令 2. 项目私有规则：`AGENT_RULES.local.md`（如存在） 3. 仓库规则：`.agents/` 与 `AGENTS.md` 4. 本文件 -## 安全与沟通 - -### 安全红线 - -- 不得在代码、日志或注释中写入明文密钥、密码、Token -- 修改鉴权、权限或敏感数据流时，必须说明动机与风险 -- 不确定是否敏感时，一律按敏感信息处理 -- 执行会修改文件系统的命令前，必须说明目的与潜在影响 - -### 沟通原则 +## 沟通原则 - 统一使用简体中文 - 专业、直接、简洁，避免对话填充词 - 发现用户理解有误时，礼貌纠正 -- 无法满足请求时，简洁说明原因并提供替代方案 +- 无法满足请求时，简洁说明原因；如有可行替代方案则一并给出 - 不给时间估算，专注事实、风险与下一步 -- 代码块必须标注语言类型 -- 不使用 emoji，除非用户明确要求 - -## 工作原则 - -- 模仿项目现有风格，先看周围代码、配置和测试再动手 -- 不假设库、框架或命令可用，先验证再使用 -- 完整覆盖用户请求，不遗漏边界条件和收尾工作 -- 技术准确性优先于迎合；不确定时先调查再回答 -- 只做当前任务需要的改动，不顺手加功能、不顺手重构 -- 不为一次性操作增加抽象，不为假设的未来需求设计 ## 项目边界 @@ -49,10 +29,9 @@ 业务文档或当前项目私有规则 - 除非用户明确要求维护、升级或调试 Playbook 本身，不得修改 `{{PLAYBOOK_ROOT}}/` 下内容 -- 当前项目已生效的规则入口是项目根目录的 `AGENT_RULES.md`、 - `AGENT_RULES.local.md`、`AGENTS.md` 与 `.agents/` -- `{{PLAYBOOK_ROOT}}/templates/` 与 `{{PLAYBOOK_ROOT}}/rulesets/` - 是模板源；不要把它们当作当前项目已生效规则 +- 当前项目的生效规则是项目根目录的 `AGENT_RULES.md`、`AGENT_RULES.local.md`、 + `AGENTS.md` 与 `.agents/`；`{{PLAYBOOK_ROOT}}/templates/` 与 + `{{PLAYBOOK_ROOT}}/rulesets/` 只是模板源，不是当前项目已生效规则 - 可按 `.agents/` 指向读取 `{{PLAYBOOK_ROOT}}/docs/` 作为标准文档； 读取不代表该目录属于业务改动范围 - 搜索、批量修改、代码审查、归档/提交时，默认排除 `{{PLAYBOOK_ROOT}}/`； @@ -60,53 +39,41 @@ ## 会话启动 -每次新会话开始时，按顺序加载以下上下文： +每次新会话开始时，按以下建议顺序加载上下文以快速建立项目全貌； +清单中文件不存在则跳过： -1. `AGENT_RULES.local.md`：项目私有规则（如存在） -2. `.agents/index.md`：语言规则与工具入口（如存在） +1. `AGENT_RULES.local.md`：项目私有规则 +2. `.agents/index.md`：语言规则与工具入口 3. `memory-bank/project-brief.md`：项目定位、边界、约束 4. `memory-bank/tech-context.md`：技术上下文、工具链、验证命令 5. `memory-bank/system-patterns.md`：系统模式、边界与不变量 6. `memory-bank/active-context.md`：当前目标、最近变更、下一步 -7. `memory-bank/decisions.md`：重要决策记录（如存在） -8. `memory-bank/progress.md`：执行进度与 Plan 状态（如存在） -9. `docs/superpowers/specs/`：最新设计稿（如存在） -10. `docs/superpowers/plans/`：相关实施计划（如存在） +7. `memory-bank/decisions.md`：重要决策记录 +8. `memory-bank/progress.md`：执行进度与 Plan 状态 +9. `docs/superpowers/specs/`：最新设计稿 +10. `docs/superpowers/plans/`：相关实施计划 -目的：快速建立项目全貌，避免重复解释和重复试错。 - -在完成本节启动加载前，不得修改文件、运行项目命令或给出实现结论。 +**执行约束**：加载顺序可调整，但在处理首个实质性任务前（修改文件、运行项目命令、给出实现结论），必须先完成上述相关上下文加载。 ## 规划与执行模型 -- 头脑风暴使用 `$brainstorming`，产出 - `docs/superpowers/specs/*-design.md` -- 实施计划使用 `$writing-plans`，产出 - `docs/superpowers/plans/*.md` -- Plan 生命周期由 `main_loop.py` 协调，并通过 - `memory-bank/progress.md` 留痕 -- 默认执行器是 `$executing-plans` -- 代码类执行必须同时遵循： - `karpathy-guidelines`、`.agents/`、`AGENT_RULES.md` - -重要约束： +> 记号约定：`$` 表示在对话中点名触发的 skill（如 +> `$brainstorming`）；无 `$` 的同名 skill 指其阶段或产物，二者指向同一 skill。 +> `using-superpowers` 是会话启动时判断并加载适用 skill 的入口 skill。 - 规划阶段必须走 `using-superpowers -> brainstorming -> writing-plans` -- `brainstorming` 写出 spec 后，立即用 `playbook.py -record-spec` - 记录 `phase=planning` 与 `spec=` -- `writing-plans` 写出 plan 后，立即用 `playbook.py -record-plan` - 记录 `plan=`、`executor=executing-plans`、 +- `$brainstorming` 产出 `docs/superpowers/specs/*-design.md`；写出 spec 后 + 立即用 `playbook.py -record-spec` 记录 `phase=planning` 与 `spec=` +- `$writing-plans` 产出 `docs/superpowers/plans/*.md`；写出 plan 后立即用 + `playbook.py -record-plan` 记录 `plan=`、`executor=executing-plans`、 `constraints=karpathy-guidelines,.agents,AGENT_RULES` -- spec/plan 产出阶段不单独提交或归档，只做文件落地与状态留痕； - 如外部 skill 要求写完 spec 或 plan 后立即提交，以本文件为准推迟到 - Plan 完成后统一处理 -- 未领取 Plan 前，不得直接进入 `$executing-plans` -- 已领取 Plan 后，默认执行使用 `$executing-plans` -- `$subagent-driven-development` 仅在 Plan 或平台明确要求时使用， - 不是默认执行器 -- 执行完成后，必须先运行 `main_loop.py finish` 写回状态， - 再更新 `progress.md` 上半部分摘要，并按主循环收尾要求归档当前 - Plan 变更 +- spec/plan 产出阶段不单独提交或归档，只做文件落地与状态留痕；如外部 skill + 要求写完后立即提交，以本文件为准，推迟到 Plan 完成后统一处理 +- Plan 生命周期由 `main_loop.py` 协调，通过 `memory-bank/progress.md` 留痕 +- Plan 执行入口只能是主循环：领取前不得进入 `$executing-plans`，领取后默认用 + `$executing-plans` 执行，`$subagent-driven-development` 仅在 Plan 或平台明确要求时使用 +- 代码类执行必须同时遵循 `$karpathy-guidelines`、`.agents/`、`AGENT_RULES.md` +- 执行完成后按「Plan 完成归档契约」收尾 ### 条件触发 Skills @@ -128,17 +95,13 @@ - `Plan Meta` 必填，位于 Plan 头部 `---` 之后、Task 1 之前 - `Plan Meta` 至少包含： - - `Plan Group` - - `Parent Plan` - `Verification Scope` - `Verification Gate` -- Plan 中不得包含必然失败或依赖未确认的信息 -- 未确认项必须在 `$brainstorming` 阶段解决后，才能产出 Plan -- Plan 内验证必须是当前阶段可通过的局部验证 -- 需要集成验证的内容，放入上层或集成 Plan -- Plan 生成完成后，执行入口只能是主循环 -- 代码类 Plan 应显式声明执行约束： - `karpathy-guidelines`、`.agents/`、`AGENT_RULES.md` +- Plan 不得包含必然失败或未确认的内容；未确认项须在 `$brainstorming` + 阶段解决后才能产出 Plan +- Plan 内验证必须是当前阶段可通过的局部验证；跨 Plan 的集成验证自成一个独立 Plan +- 每个 Plan 应自身可独立交付，不依赖其他 Plan 的执行结果；有先后顺序的工作 + 放入同一 Plan 的有序 Task，不跨 Plan 表达执行依赖 - 不因等待确认而中断可执行步骤；待确认事项写入回复 - 每个 Plan 应小步、可验证、可快速完成 @@ -168,7 +131,7 @@ ### 领取与写回 -领取命令： +**领取 Plan**： ```bash python {{PLAYBOOK_SCRIPTS}}/main_loop.py claim \ @@ -177,68 +140,33 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py claim \ -owner "<当前session或agent标识>" ``` -该命令会在锁保护下串行完成三件事： +该命令在锁保护下完成：自动识别当前环境（windows/linux/darwin）、校验 Plan Meta、优先恢复 `in-progress`、选择第一个可执行 Plan、写入 `claimed_by`/`claimed_at` 并清理上一轮 `verification`。 -- 自动识别当前环境：`windows`、`linux`、`darwin` -- 校验 Plan 文件包含必需 `Plan Meta` -- 已有 `in-progress` 优先恢复 -- 如无 `in-progress`，按 Plan 文件顺序选择第一个可执行 Plan： - `pending` 或 `blocked: env:<当前环境>:...` -- 将选中的 Plan 写成 `in-progress` -- 在 `workflow-state` 写入 `claimed_by`、`claimed_at`，并清理上一轮 - `verification` +stdout 必须包含 `PLAN=`；如为环境恢复，还会附带 `NOTE=env:<环境>:`。 -这里的锁保护的是 `progress.md` 状态块更新，避免多个 session -同时读写时发生覆盖。 - -stdout 必须包含： - -- `PLAN=` -- 如为环境恢复，还会附带 `NOTE=env:<环境>:` - -规划与执行留痕示例： - -```bash -# brainstorming 完成后 -python {{PLAYBOOK_SCRIPTS}}/playbook.py \ - -record-spec docs/superpowers/specs/-design.md \ - -progress memory-bank/progress.md -``` - -```bash -# writing-plans 完成后 -python {{PLAYBOOK_SCRIPTS}}/playbook.py \ - -record-plan docs/superpowers/plans/.md \ - -progress memory-bank/progress.md -``` - -写回命令示例： +**写回状态**： ```bash +# 完成 python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \ - -plan \ - -status done \ + -plan -status done \ -progress memory-bank/progress.md \ -verified "<本轮已通过的验证命令或证据>" -``` -```bash +# 阻塞（环境） python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \ - -plan \ - -status blocked \ + -plan -status blocked \ -progress memory-bank/progress.md \ -note "env:<所需环境>:" -``` -```bash +# 阻塞/跳过（其他原因） python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \ - -plan \ - -status blocked|skipped \ + -plan -status blocked|skipped \ -progress memory-bank/progress.md \ -note "<原因>" ``` -只读状态命令： +**查看状态**（只读，不修改 progress.md）： ```bash python {{PLAYBOOK_SCRIPTS}}/main_loop.py status \ @@ -246,14 +174,24 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py status \ -progress memory-bank/progress.md ``` -`status` 只汇总 `pending`、`in-progress`、`done`、`blocked`、 -`skipped` 和当前 `workflow-state`，不得修改 `progress.md`。 +**规划留痕**： + +```bash +# brainstorming 完成后 +python {{PLAYBOOK_SCRIPTS}}/playbook.py \ + -record-spec docs/superpowers/specs/-design.md \ + -progress memory-bank/progress.md + +# writing-plans 完成后 +python {{PLAYBOOK_SCRIPTS}}/playbook.py \ + -record-plan docs/superpowers/plans/.md \ + -progress memory-bank/progress.md +``` ### Plan 场景下的执行上下文与隔离策略 - 本节仅适用于通过主循环领取并执行 Plan 的场景 -- 默认允许在当前项目上下文直接执行 Plan -- 不强制为 Plan 执行创建隔离上下文 +- 默认在当前项目上下文直接执行 Plan，不强制创建隔离上下文 - 仅在以下场景使用隔离工作区： - 用户明确要求隔离执行 - Plan 文本自身明确要求隔离执行 @@ -264,71 +202,50 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py status \ 1. 先 `claim`，拿到 `PLAN=` 后再读取 Plan 内容 2. 如返回 `NOTE=env:...`，本轮只执行列出的 Task -3. 默认执行器是 `$executing-plans`；代码类任务在执行前必须显式 - 加载 `karpathy-guidelines` -4. 执行时同时遵循 `.agents/`、`AGENT_RULES.md` 和 Plan 本身； - 如发生冲突，以优先级更高的规则为准 +3. 代码类任务在执行前必须显式加载 `$karpathy-guidelines` +4. 执行时同时遵循 `.agents/`、`AGENT_RULES.md` 和 Plan 5. 按顺序执行 Task，并完成 Plan 约定的验证 6. 环境不匹配时，记录所需环境和 Task，继续处理本 Plan 其余可执行 Task 7. 其他阻塞写回 `blocked`；永久放弃写回 `skipped` -8. 触碰安全红线时立即停止，不继续后续 Plan -9. 常规模式下可对高风险事项向用户确认；无交互模式按本文件 - 的“需要确认的场景”自动处理 -10. 每次 `claim` 只领取一个 Plan；写回并归档当前 Plan 变更后 - 再领取下一个 -11. 全部 Plan 处理完后，统一汇总完成项、阻塞项、跳过项、 +8. 遇到决策点时按「需要确认的场景」处理：常规模式下满足该节 + 条件的先向用户确认；无交互模式按该节自动处理 +9. 每次 `claim` 只领取一个 Plan；写回并归档当前 Plan 变更后 + 再领取下一个 +10. 全部 Plan 处理完后，统一汇总完成项、阻塞项、跳过项、 环境需求与待确认事项 ### Plan 完成归档契约 -- 归档指按当前项目约定创建可回溯的交付记录；具体机制由项目本地规则 - 或用户指令定义 -- `main_loop.py finish -status done` 只负责写回机器状态，不代表 Plan - 已完成交付；memory 更新或回复摘要也不等同于归档 -- Plan `done` 后必须完成当前 Plan 变更的归档/提交，然后才能继续领取下一个 - Plan；归档方式由项目约定决定 -- spec/plan 本身属于后续 Plan 交付边界的一部分，不在规划阶段拆成独立 - 归档/提交单元 -- 收尾顺序： +**核心原则**： + +- Plan `done` 后必须完成当前 Plan 变更的归档/提交，然后才能继续领取下一个 Plan +- `main_loop.py finish -status done` 只负责写回机器状态，不自动提交或归档，不代表已完成交付 +- Plan 范围是归档/提交边界，不以整个工作区是否干净作为唯一判断 + +**收尾顺序**： 1. 完成 Plan 约定验证 -2. 运行 `main_loop.py finish -status done -verified "<证据>"` - 写回状态 +2. 运行 `main_loop.py finish -status done -verified "<证据>"` 写回状态 3. 必要时更新 `progress.md` 上半部分摘要和相关 memory 4. 检查当前变更清单与差异 5. 只归档/提交当前 Plan 相关改动 -- 当前 Plan 相关改动包括但不限于： - - 本轮代码、配置、测试、模板改动 - - 当前 Plan 文件（创建、补充、勾选 Task、记录结果等） - - `memory-bank/progress.md` 中本轮 `workflow-state`、`plan-status` - 与摘要更新 - - 必要 memory 更新，例如 `active-context.md`、`decisions.md` -- Plan 范围是归档/提交边界，不以整个工作区是否干净作为唯一判断 -- 允许存在其他 session 的未归档改动，只要它们不属于当前 Plan、 - 不与当前 Plan 范围冲突、且不会被混入本轮归档/提交 -- 不得由 `main_loop.py finish` 自动执行提交或变更归档 -- 不得把用户已有改动或其他 Plan 的改动混入当前 Plan 交付单元 +**当前 Plan 相关改动包括**： + +- 本轮代码、配置、测试、模板改动 +- 当前 Plan 文件（创建、补充、勾选 Task、记录结果等） +- `memory-bank/progress.md` 中本轮 `workflow-state`、`plan-status` 与摘要更新 +- 必要 memory 更新（如 `active-context.md`、`decisions.md`） + +**归档约束**： + +- 不得把用户已有改动或其他 Plan/session 的改动混入当前 Plan 交付单元； + 这类改动只要不属于、不冲突当前 Plan，允许其未归档共存 - 如 Plan `done` 后没有当前 Plan 相关差异，必须在回复中说明无归档原因 -- 如当前 Plan 相关差异仍未归档，只能声明“状态已写回，交付未完成”， - 不得声明 Plan 完成 -- `blocked` / `skipped` 不默认归档/提交代码改动；只有状态留痕或已验证的 - 局部成果需要保留时才归档/提交 -- 继续领取下一个 Plan 前，必须确认当前 Plan 无遗留差异；如剩余差异属于 - 其他 session 或其他 Plan，保留在原处并在报告中说明 -- 如剩余差异与当前 Plan 或下一个 Plan 的预期范围冲突，常规模式先向用户 - 确认；无交互模式写入风险并停止继续领取 - -## 通用执行约束 - -### 代码与配置修改 - -- 必须先读文件再修改 -- 遵循 `.agents/`、项目代码风格和现有命名约定 -- 只改必要部分，不顺手重构无关内容 -- 执行与改动相称的验证；如有相关测试且未被豁免，必须通过 -- 遵循项目声明的换行与文件格式规则 +- 如当前 Plan 相关差异仍未归档，只能声称「状态已写回，交付未完成」，不得声称 Plan 完成 +- `blocked` / `skipped` 不默认归档/提交代码改动；只有状态留痕或已验证的局部成果需要保留时才归档 +- 继续领取下一个 Plan 前，必须确认当前 Plan 无遗留差异；如剩余差异与当前 Plan 或下一个 Plan 的预期范围冲突，常规模式先向用户确认；无交互模式将当前 Plan 写回 `blocked` 并记录冲突，继续领取下一个 ### 决策与留痕 @@ -340,9 +257,8 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py status \ 阶段变化或执行结束后整理/替换摘要，不做无限追加 - `active-context.md` 是短期上下文快照，不是长期日志； 只保留当前 Plan / 下一轮仍重要的目标、变化、文件与下一步 -- 同一错误重复两次以上时，立即更新 - `AGENT_RULES.local.md` 或 `memory-bank/decisions.md` -- 发现项目特有规律时，沉淀到 `AGENT_RULES.local.md` +- 同一错误重复两次以上，或发现项目特有规律时，沉淀到 + `AGENT_RULES.local.md`（决策类记入 `memory-bank/decisions.md`） ### 归档操作 @@ -351,44 +267,43 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py status \ - 不跳过项目约定的归档前检查 - 如项目没有归档机制，在回复中列出本轮交付的文件清单与验证证据 -### 工具使用 - -- 独立步骤尽可能并行执行 -- 严格遵循工具参数定义与 schema -- 优先使用专用工具，不重复探测同一信息 -- 文本搜索优先使用 `rg` - ## 需要确认的场景 ### 常规模式 +执行 Plan 过程中，遇到以下决策点先向用户确认： + - 需求不明确，或存在多种可行方案 - 需要行为、兼容性或性能取舍 - 涉及架构变更、破坏性修改或约束冲突 - 风险较高，且继续执行可能放大返工成本 -### 无交互模式 - -- 安全红线：立即停止，不继续后续 Plan -- 架构变更、兼容性问题、破坏性修改：写回 `blocked` -- 多种可行方案：选择最保守方案，并在报告中说明理由 -- 一般歧义、风险或决策点：记录到报告，继续执行安全部分 - -### 可以直接执行 +以下 Plan 改动可直接推进，无需确认： - 明显的 bug 修复 - 符合现有模式的小改动 - 测试用例补充或局部验证补齐 +### 无交互模式 + +严格按 Plan 的 Task 执行，不自行做设计决策；一个 Plan 卡住不影响其余 Plan， +继续领取下一个，直到所有 Plan 处理完毕： + +- Task 明确可执行：直接执行 +- Task 存在歧义或需要未在 Plan 中确认的设计决策：写回 `blocked`，不猜测、不替代设计 + （此类决策本应在 `$brainstorming` 阶段解决，缺失说明 Plan 不合格） +- 需要架构变更、破坏性修改，且 Plan 未明确授权：写回 `blocked` +- 环境不匹配：记录 `env:<环境>:`，跳过该 Task，继续本 Plan 其余 Task + +每个被 `blocked` 的 Plan 记录原因，继续领取下一个，不因单个 Plan 卡住而中止整批。 + ## Session 收尾 -- 汇总已完成、阻塞、跳过的 Plan 及原因 -- 标出需要其他环境处理的事项：`env:<环境>:` -- 必要时将重要结论写入 `memory-bank/decisions.md` -- 出现以下情况时，建议开启新 Session： - - 当前方向明显跑偏 - - 讨论阶段产出多个候选方案，准备进入执行 - - Session 过长，开始重复犯同类错误 +出现以下情况时，建议开启新 Session： + +- 当前方向明显跑偏 +- 讨论阶段产出多个候选方案，准备进入执行 +- Session 过长，开始重复犯同类错误 ## 验证清单 diff --git a/templates/README.md b/templates/README.md index f5fb65d9..2f55e094 100644 --- a/templates/README.md +++ b/templates/README.md @@ -1,202 +1,188 @@ # 项目架构模板 -本目录包含以 `superpowers` 为基石的项目模板，用于快速初始化新项目的 -AI 代理工作环境。 +本目录包含基于 superpowers 工作流的项目模板，用于快速初始化 AI 代理工作环境。 + +## 与 Playbook 其他部分的关系 + +```text +playbook/ +├── rulesets/ # 语言级硬规则 → 部署到 .agents/ +├── skills/ # 按需加载的技能 +├── docs/ # 权威静态文档 +├── templates/ # 本目录：项目架构模板 → 部署到 memory-bank/ 等 +└── scripts/ + └── playbook.py # 统一入口 +``` + +部署方式详见主 README.md 的"在其他项目中使用本 Playbook"章节。 ## 目录结构 ```text templates/ -├── README.md # 本文件 ├── AGENTS.template.md # 入口导航模板 -├── AGENT_RULES.template.md # superpowers-first 执行规则模板 -├── memory-bank/ # 项目上下文模板 -│ ├── project-brief.template.md -│ ├── tech-context.template.md -│ ├── system-patterns.template.md -│ ├── active-context.template.md -│ ├── progress.template.md -│ └── decisions.template.md -├── prompts/ # 任务入口模板（不是流程权威） -│ ├── README.md -│ ├── system/ -│ │ └── agent-behavior.template.md -│ ├── coding/ -│ │ ├── clarify.template.md -│ │ ├── verify-change.template.md -│ │ ├── close-task.template.md -│ │ ├── update-memory.template.md -│ │ └── code-review.template.md -├── ci/ # CI 模板 -│ ├── README.md -│ └── gitea/ -│ └── .gitea/ -│ ├── workflows/ -│ └── ci/ -├── cpp/ # C++ 配置模板 -│ ├── .clang-format -│ ├── .clangd -│ └── ... -└── python/ # Python 配置模板 - ├── .editorconfig - ├── pyproject.toml - └── ... +├── AGENT_RULES.template.md # superpowers 执行规则模板 +├── memory-bank/ # 项目上下文模板（6 个） +├── prompts/ # 任务入口模板（6 个 + README） +├── ci/ # CI 配置模板 +├── cpp/ # C++ 工具链模板 +└── python/ # Python 工具链模板 ``` -## 文件分类 +## 模板分类 -从部署角度看，本目录的文件分成三类： +从部署和维护角度，模板分为三类： -- **会同步更新的框架模板** - - `AGENT_RULES.md` - - `docs/prompts/README.md` - - `docs/prompts/system/*.md` - - `docs/prompts/coding/*.md` - - `AGENTS.md`、`CLAUDE.md`（按 playbook 区块更新） -- **首次创建后由项目维护的上下文文件** - - `memory-bank/*.md` - - `AGENT_RULES.local.md` -- **只保留在快照中参考的模板** - - `ci/` - - `cpp/` - - `python/` +### 1. 框架模板（会自动更新） -补充说明： +这些文件由 playbook 框架维护，每次同步时可能更新： -- `memory-bank/*.md` 首次创建后应由项目填写；`force=true` - 会覆盖已填写内容并先备份。 -- `AGENT_RULES.local.md` 由 `[sync_rules]` 首次自动创建， - 后续不再覆盖。 -- `docs/prompts/custom/` 和项目新增的 `docs/prompts/**/*` - 不会被 playbook 删除。 -- `CLAUDE.md` 如已有 playbook 区块则更新；如未引用 - `@AGENTS.md` 则追加；如已手工引用 `@AGENTS.md` 则跳过。 -- 流程约束统一收敛到 `AGENT_RULES.md`；`docs/prompts/` - 只负责把代理导向正确的任务入口。 +- `AGENT_RULES.md` +- `AGENTS.md`、`CLAUDE.md`（按 playbook 区块更新） +- `docs/prompts/README.md` +- `docs/prompts/system/*.md` +- `docs/prompts/coding/*.md` -## 快速部署 +### 2. 项目上下文（首次创建后由项目维护） -以下命令假设 **playbook 已经部署到项目内**，使用统一入口 `playbook.py`，配置节存在即启用： +这些文件首次创建后应由项目填写，`force=true` 会覆盖已填写内容并先备份： + +- `memory-bank/*.md` +- `AGENT_RULES.local.md`（首次自动创建，后续不再覆盖） + +### 3. 参考模板（需手动复制） + +这些模板保留在快照中供参考，需手动复制到项目根目录： + +- `ci/`：Gitea Actions 工作流 +- `cpp/`：C++ 工具链配置 +- `python/`：Python 工具链配置 + +**补充说明**： + +- `docs/prompts/custom/` 和项目新增的 `docs/prompts/**/*` 不会被 playbook 删除 +- `CLAUDE.md` 如已有 playbook 区块则更新；如未引用 `@AGENTS.md` 则追加；如已手工引用则跳过 +- 流程约束统一收敛到 `AGENT_RULES.md`；`docs/prompts/` 只负责把代理导向正确的任务入口 + +## 部署方式 + +使用 `playbook.py` 统一入口部署，通过配置节控制同步内容： ```toml # playbook.toml -[playbook] -project_root = "/path/to/project" -playbook_root = "docs/standards/playbook" -install_mode = "snapshot" - -# 同步 AGENT_RULES.md（配置节存在即启用） -[sync_rules] -# force = true # 可选，强制覆盖已存在的文件 - -# 同步 memory-bank/（配置节存在即启用） -[sync_memory_bank] -project_name = "MyProject" -# force = true # 可选，强制覆盖（会先备份） - -# 同步 docs/prompts/（配置节存在即启用） -[sync_prompts] -# force = true # 可选，强制覆盖（会先备份） +[sync_rules] # 同步 AGENT_RULES.md +[sync_memory_bank] # 同步 memory-bank/ +[sync_prompts] # 同步 docs/prompts/ ``` -```bash -python /scripts/playbook.py -config playbook.toml -``` +详细配置说明见主 README.md 和 playbook.toml.example。 -参数说明见 `playbook.toml.example`（仓库根目录）或项目内的 -`/playbook.toml.example`。 +## 模板说明 -其中 `` 默认为 `docs/standards/playbook`， -也可以按项目配置改成 `custom/playbook` 等自定义目录； -对应文档入口会变成 `/docs/...`。 +### memory-bank/ -如果你当前是在 **外部 clone 的 playbook 仓库** 中执行，而不是在目标项目内执行快照，请使用： +项目上下文文档，用于让 AI 快速理解项目： -```bash -python scripts/playbook.py -config playbook.toml -``` +| 文件 | 用途 | +| ----------------------------- | -------------------------- | +| `project-brief.template.md` | 项目定位、边界、约束 | +| `tech-context.template.md` | 技术上下文、工具链、入口 | +| `system-patterns.template.md` | 系统模式、边界、不变量 | +| `active-context.template.md` | 当前目标、最近变更、下一步 | +| `progress.template.md` | 人类摘要 + Plan 状态块 | +| `decisions.template.md` | 架构决策记录（ADR） | -此时 `install_mode = "snapshot"` 会把快照写入 `/`； -后续再在目标项目内使用 `/scripts/playbook.py` -做同步更新。 +### prompts/ -### 配置节说明 +任务入口模板，部署后去掉 `.template` 后缀。`prompts/README.md` 作为任务入口索引。 -- `[sync_rules]`：部署 `AGENT_RULES.md`；必要时创建 `.local.md`。 - 选项：`force`、`no_backup`、`date` -- `[sync_memory_bank]`：部署 `memory-bank/`。 - 选项：`project_name`、`force`、`no_backup`、`date` -- `[sync_prompts]`：部署 `docs/prompts/`。 - 选项：`force`、`no_backup`、`date` -- `[sync_standards]`：部署 `.agents//`。 - 选项：`langs`、`gitattr_mode`、`no_backup` -- `[install_skills]`：部署到 `~/.agents/skills/` 或 - `~/.claude/skills/`。 - 选项：`mode`、`skills`、`agents_home`、`skill_link`、 - `no_backup` +| 文件 | 用途 | 使用场景 | +| ----------------------------------- | ------------ | ------------------- | +| `system/agent-behavior.template.md` | 入口路由模板 | 选择执行路径 | +| `coding/clarify.template.md` | 需求澄清模板 | 需求不明确时 | +| `coding/verify-change.template.md` | 变更验证模板 | 声称完成前验证 | +| `coding/close-task.template.md` | 本轮收尾模板 | 一轮工作结束时 | +| `coding/update-memory.template.md` | 回写记忆模板 | 上下文变化后回写 | +| `coding/code-review.template.md` | 代码评审入口 | 执行 MR/PR 代码评审 | -- **配置节存在即启用**：只写需要同步的配置节 -- **AGENTS.md**：始终按区块更新（``），不受配置节控制 -- **CLAUDE.md**：自动检测/创建；如已存在 playbook 区块则更新，如未引用 `@AGENTS.md` 则追加，否则跳过 -- **force**：默认 false，已存在则跳过；设为 true 时覆盖框架文件（会先备份） -- **no_backup**：默认 false；设为 true 时跳过备份直接覆盖 -- **不删除项目文件**：只更新框架提供的文件，项目新增的文件不会被删除 -- **占位符替换**：自动替换 `{{DATE}}`、`{{PROJECT_NAME}}`、`{{PLAYBOOK_ROOT}}`、`{{PLAYBOOK_SCRIPTS}}` +### AGENT_RULES.template.md -### 典型场景 +执行规则模板，定义 AI 的工作循环和约束。如需项目私有规则，建议维护 `AGENT_RULES.local.md`；该文件通常由 `[sync_rules]` 首次自动创建，其优先级高于 `AGENT_RULES.md`，且后续不会被 playbook 覆盖。 -```toml -# 场景 1：初次部署（全部） -[sync_rules] -[sync_memory_bank] -project_name = "MyProject" -[sync_prompts] +计划编排与执行细节统一指向 `docs/superpowers/`、`playbook.py -record-spec/-record-plan` 与 `main_loop.py claim/finish`。 -# 场景 2：框架升级（只更新规则） -[sync_rules] -force = true +### AGENTS.template.md -# 场景 3：重置项目上下文 -[sync_memory_bank] -project_name = "MyProject" -force = true -``` +入口导航模板，作为项目的主入口（Codex 入口）。 -### docs/superpowers 命名约定 +**设计理念**： + +- **最小化内容**：只包含导航链接，不包含详细规则 +- **结构化导航**：分为核心规则、项目上下文、任务入口三个板块 + +**playbook 标记**（用于自动更新）： + +- ``：语言规则链接，由 `[sync_standards]` 管理 +- ``：路由链接，`AGENTS.md` 始终按区块更新 +- ``：完整框架，`AGENTS.md` 始终按区块更新 + +### superpowers 工作流约定 `docs/superpowers/` 统一承载设计稿和实施计划： -- 设计只落到 `specs/` -- 计划只落到 `plans/` -- 执行状态只写回 `memory-bank/progress.md` - -为与 thirdparty `superpowers` 上游当前工作流对齐，建议统一使用： - -- `docs/superpowers/specs/YYYY-MM-DD--design.md`： - `brainstorming` 产出的设计稿 -- `docs/superpowers/plans/YYYY-MM-DD-.md`： - `writing-plans` 产出的实施计划 +- **设计稿**：`specs/YYYY-MM-DD--design.md`（`brainstorming` 产出） +- **实施计划**：`plans/YYYY-MM-DD-.md`（`writing-plans` 产出） +- **执行状态**：回写到 `memory-bank/progress.md` 其中 `plans/` 为主执行入口；`specs/` 只作为设计背景和上游文档。 -### 生命周期总览 - -完整主链只在 `AGENT_RULES.template.md` 定义；本文件不重复展开。 -这里仅说明职责分层： +**生命周期**： - `docs/prompts/`：任务入口层，只负责把代理导向正确入口 - `docs/superpowers/specs/`：设计稿 - `docs/superpowers/plans/`：实施计划与主执行输入 - `memory-bank/progress.md`：执行状态留痕 +完整主链只在 `AGENT_RULES.template.md` 定义。 + +### 语言配置模板（ci/、cpp/、python/） + +语言和 CI 配置模板，`install_mode = "snapshot"` 安装快照时会复制这些模板： + +- `ci/gitea/`：Gitea Actions 工作流与辅助脚本，部署到快照 `templates/ci/` +- `cpp/`：`.clang-format`、`.clangd`、`CMakeLists.txt` 等文件，部署到快照 `templates/cpp/` +- `python/`：`pyproject.toml`、`.editorconfig` 等文件，部署到快照 `templates/python/` + +**使用方式**：这些模板保留在快照中供参考，需手动复制到项目根目录使用。其中 `ci/gitea/` 应按 `templates/ci/README.md` 的说明，整块复制 `.gitea/` 目录。 + +## 技术细节 + +### 占位符说明 + +模板中使用 `{{PLACEHOLDER}}` 格式的占位符，需要替换为实际值： + +| 占位符 | 说明 | 自动替换 | +| ------------------------- | ------------ | -------- | +| `{{DATE}}` | 日期 | ✅ 是 | +| `{{PROJECT_NAME}}` | 项目名称 | ✅ 可选 | +| `{{PLAYBOOK_ROOT}}` | Playbook 根 | ✅ 是 | +| `{{PLAYBOOK_SCRIPTS}}` | 脚本路径 | ✅ 是 | +| `{{PROJECT_GOAL}}` | 项目目标 | ❌ 手动 | +| `{{PROJECT_DESCRIPTION}}` | 项目描述 | ❌ 手动 | +| 其他 `{{...}}` | 项目特定内容 | ❌ 手动 | + +- `{{PROJECT_NAME}}` 可通过 `sync_memory_bank.project_name` 自动替换；未配置时保持原样 +- `{{PLAYBOOK_ROOT}}` 自动替换为项目内 Playbook 根目录（默认 `docs/standards/playbook`） +- `{{PLAYBOOK_SCRIPTS}}` 自动替换为 Playbook 脚本路径（默认 `docs/standards/playbook/scripts`） + ### 部署后的目录结构 ```text project/ ├── AGENTS.md # 入口导航（Codex 入口） -├── AGENT_RULES.md # superpowers-first 执行规则 +├── AGENT_RULES.md # superpowers 执行规则 ├── AGENT_RULES.local.md # 项目私有规则（自动创建，项目维护） -├── CLAUDE.md # Claude Code 入口（按规则维护/追加 playbook 区块） +├── CLAUDE.md # Claude Code 入口 ├── memory-bank/ # 项目上下文 │ ├── project-brief.md │ ├── tech-context.md @@ -219,143 +205,6 @@ project/ └── plans/ # writing-plans / main_loop 消费 ``` -## 占位符说明 - -模板中使用 `{{PLACEHOLDER}}` 格式的占位符，需要替换为实际值： - -| 占位符 | 说明 | 自动替换 | -| ------------------------- | ------------ | -------- | -| `{{DATE}}` | 日期 | ✅ 是 | -| `{{PROJECT_NAME}}` | 项目名称 | ✅ 可选 | -| `{{PROJECT_GOAL}}` | 项目目标 | ❌ 手动 | -| `{{PROJECT_DESCRIPTION}}` | 项目描述 | ❌ 手动 | -| `{{PLAYBOOK_ROOT}}` | Playbook 根 | ✅ 是 | -| `{{PLAYBOOK_SCRIPTS}}` | 脚本路径 | ✅ 是 | -| 其他 `{{...}}` | 项目特定内容 | ❌ 手动 | - -`{{PROJECT_NAME}}` 可通过 `sync_memory_bank.project_name` 自动替换； -未配置时保持原样。 -`{{PLAYBOOK_ROOT}}` 自动替换为项目内 Playbook 根目录 -（默认 `docs/standards/playbook`， -也可按项目配置改成 `custom/playbook` 等）。 -`{{PLAYBOOK_SCRIPTS}}` 自动替换为 Playbook 脚本路径 -（默认 `docs/standards/playbook/scripts`， -也可按项目配置改成 `custom/playbook/scripts` 等）。 - -## 模板说明 - -### memory-bank/ - -项目上下文文档，用于让 AI 快速理解项目： - -| 文件 | 用途 | -| ----------------------------- | -------------------------- | -| `project-brief.template.md` | 项目定位、边界、约束 | -| `tech-context.template.md` | 技术上下文、工具链、入口 | -| `system-patterns.template.md` | 系统模式、边界、不变量 | -| `active-context.template.md` | 当前目标、最近变更、下一步 | -| `progress.template.md` | 人类摘要 + Plan 状态块 | -| `decisions.template.md` | 架构决策记录（ADR） | - -### prompts/ - -任务入口模板（部署后去掉 `.template` 后缀）： - -其中 `templates/prompts/README.md` 部署后对应 `docs/prompts/README.md`， -作为任务入口索引。 - -| 文件 | 用途 | 使用场景 | -| ----------------------------------- | ------------ | ------------------- | -| `system/agent-behavior.template.md` | 入口路由模板 | 选择执行路径 | -| `coding/clarify.template.md` | 需求澄清模板 | 需求不明确时 | -| `coding/verify-change.template.md` | 变更验证模板 | 声称完成前验证 | -| `coding/close-task.template.md` | 本轮收尾模板 | 一轮工作结束时 | -| `coding/update-memory.template.md` | 回写记忆模板 | 上下文变化后回写 | -| `coding/code-review.template.md` | 代码评审入口 | 执行 MR/PR 代码评审 | - -### AGENT_RULES.template.md - -执行规则模板，定义 AI 的工作循环和约束。 -如需项目私有规则，建议维护 `AGENT_RULES.local.md`；该文件通常由 `[sync_rules]` -首次自动创建，其优先级高于 `AGENT_RULES.md`，且后续不会被 `playbook.py` 覆盖。 -计划编排与执行细节统一指向 `docs/superpowers/`、 -`playbook.py -record-spec/-record-plan` 与 `main_loop.py claim/finish`； -这里仅说明模板职责与部署边界。 - -### AGENTS.template.md - -入口导航模板，作为项目的主入口。 - -**设计理念**： - -- **最小化内容**：只包含导航链接，不包含详细规则 -- **结构化导航**：分为核心规则、项目上下文、任务入口三个板块 - -**playbook 标记**（用于自动更新）： - -- ``：语言规则链接。 - 由 `[sync_standards]` 管理 -- ``：路由链接。 - `AGENTS.md` 始终按区块更新 -- ``：完整框架。 - `AGENTS.md` 始终按区块更新 - -### ci/、cpp/、python/ - -语言和 CI 配置模板。`install_mode = "snapshot"` 安装快照时会复制这些模板： - -- `ci/gitea/`：Gitea Actions 工作流与辅助脚本。 - 部署到快照 `templates/ci/` -- `cpp/`：`.clang-format`、`.clangd`、`CMakeLists.txt` - 等文件。 - 部署到快照 `templates/cpp/` -- `python/`：`pyproject.toml`、`.editorconfig` 等文件。 - 部署到快照 `templates/python/` - -> 注意：这些模板会复制到快照的 `templates/` 目录，需手动从快照复制到项目根目录使用。 -> 其中 `ci/gitea/` 应按 `templates/ci/README.md` 的说明，整块复制 `.gitea/` 目录，而不只是复制 workflows。 - -**使用方式**： - -```toml -# playbook.toml - 生成包含这些模板的快照 -[playbook] -project_root = "/path/to/project" -playbook_root = "docs/standards/playbook" -install_mode = "snapshot" - -[sync_standards] -langs = ["tsl", "cpp", "python"] -``` - -```bash -python scripts/playbook.py -config playbook.toml -# 然后手动从 /templates/ 复制所需配置到项目根目录 -``` - -## 与 playbook 其他部分的关系 - -```text -playbook/ -├── rulesets/ # 语言级硬规则 → 部署到 .agents/ -├── skills/ # 按需加载的技能（thirdparty/ 为第三方同步） -├── docs/ # 权威静态文档 -├── templates/ # 本目录：项目架构模板 → 部署到 memory-bank/ 等 -└── scripts/ - └── playbook.py # 统一入口：snapshot install / sync_* -``` - -## 完整部署流程 - -```bash -# 1. 准备配置并执行统一入口 -python /scripts/playbook.py -config playbook.toml - -# 2. 编辑 memory-bank/*.md 填写项目信息 - -# 3. 替换剩余的 {{PLACEHOLDER}} 占位符 -``` - --- -**最后更新**：2026-05-18 +**最后更新**：2026-06-17 diff --git a/templates/prompts/meta/prompt-generator.template.md b/templates/prompts/meta/prompt-generator.template.md deleted file mode 100644 index 46d10d63..00000000 --- a/templates/prompts/meta/prompt-generator.template.md +++ /dev/null @@ -1,126 +0,0 @@ -# 提示词生成器（元提示词） - - - -## 何时使用 - -- 需要为新场景创建专用提示词 -- 现有提示词不满足特定需求 -- 需要批量生成同类提示词 - ---- - -## 生成流程（α循环） - -### 1. 分析场景 - -```markdown -**场景名称**：[名称] -**目标用户**：[AI/人类/两者] -**触发条件**：[何时使用这个提示词] -**预期输出**：[使用后应该产出什么] -``` - -### 2. 提取约束 - -```markdown -**必须做**： -- 约束1 -- 约束2 - -**禁止做**： -- 禁止1 -- 禁止2 - -**边界条件**： -- 边界1 -- 边界2 -``` - -### 3. 生成草稿 - -```markdown -# [提示词标题] - - - -## 何时使用 - -- 场景1 -- 场景2 - -## [核心内容] - -[根据场景填充] - -## [约束/原则] - -- 约束1 -- 约束2 - ---- - -**最后更新**：{{DATE}} -``` - ---- - -## 优化流程（Ω循环） - -### 1. 评估维度 - -| 维度 | 问题 | -| ---------- | ---------------------- | -| **清晰度** | 指令是否明确无歧义？ | -| **完整度** | 是否覆盖所有必要场景？ | -| **简洁度** | 是否有冗余内容可删除？ | -| **可操作** | AI 能否直接执行？ | - -### 2. 迭代优化 - -```text -草稿 → 评估 → 修改 → 再评估 → ... → 定稿 -``` - -### 3. 验证测试 - -- 用实际场景测试提示词效果 -- 收集反馈，持续迭代 - ---- - -## 提示词模板库 - -### 标准结构 - -```markdown -# [标题] - - - -## 何时使用 -## [核心内容] -## [约束/原则] - ---- - -**最后更新**：{{DATE}} -``` - -### 命名规范 - -- 文件名：`[动词]-[对象].template.md` -- 示例：`clarify-requirement.template.md` - ---- - -**最后更新**：{{DATE}} diff --git a/templates/prompts/system/agent-behavior.template.md b/templates/prompts/system/agent-behavior.template.md index 7167f5d4..1bb567a4 100644 --- a/templates/prompts/system/agent-behavior.template.md +++ b/templates/prompts/system/agent-behavior.template.md @@ -2,7 +2,7 @@ ## 路由原则 diff --git a/tests/README.md b/test/README.md similarity index 100% rename from tests/README.md rename to test/README.md diff --git a/test/agent/README.md b/test/agent/README.md new file mode 100644 index 00000000..65a0b663 --- /dev/null +++ b/test/agent/README.md @@ -0,0 +1,290 @@ +# TSL Agent 测试定义 + +这个目录包含 TSL 语法的 agent 测试用例定义，**支持测试任何 agent**。 + +--- + +## 🎯 多 Agent 支持 + +### 测试定义（通用） + +- **`test_cases.md`** - 100+ 测试用例定义（英文完整版） + - 适用于所有 agent（Claude, GPT-4, Gemini, 等） + - 包含提示词、评分标准、预期代码 + - 与具体 agent 无关 + +- **`test_cases_zh.md`** - 100+ 测试用例定义（中文完整版） + - 完整翻译版本，包含所有测试用例 + - 适合中文环境下的 agent 评估 + +### 测试结果（按 Agent 分类） + +- **`result/results__.md`** - 特定 agent 的测试结果 + - 存放目录：`test/agent/result/`（已加入 `.gitignore`） + - 命名格式：`results_{agent}_{YYYYMMDD}.md` + - 示例： + - `result/results_claude_20260610.md` - Claude 的测试结果 + - `result/results_gpt4_20240617.md` - GPT-4 的测试结果 + - `result/results_gemini_20240617.md` - Gemini 的测试结果 + +--- + +## 📁 目录结构 + +### 当前文件 + +``` +test/agent/ +├── README.md # 本文件 +├── test_cases.md # 通用测试定义（英文完整版）⭐ +├── test_cases_zh.md # 通用测试定义（中文完整版）⭐ +└── result/ # 测试结果目录（gitignore） + ├── results_claude_20260610.md + ├── results_gpt4_20240617.md + └── results_gemini_20240617.md +``` + +### 添加新 Agent 的测试结果 + +``` +test/agent/ +├── test_cases.md # 通用（不变） +├── test_cases_zh.md # 中文版（不变） +└── result/ + ├── results_claude_20260610.md # Claude + ├── results_gpt4_20240617.md # GPT-4（新增） + └── results_gemini_20240617.md # Gemini（新增） +``` + +--- + +## 🎯 使用方式 + +### 测试不同的 Agent + +1. **使用相同的测试定义** + ```bash + # 所有 agent 都使用 test_cases.md 中的测试用例 + cat test_cases.md + ``` + +2. **为每个 Agent 记录结果** + ```bash + # 创建结果目录 + mkdir -p test/agent/result + + # 测试 GPT-4 + # 结果保存为：test/agent/result/results_gpt4_20240617.md + + # 测试 Gemini + # 结果保存为：test/agent/result/results_gemini_20240617.md + + # 测试 Claude + # 结果保存为：test/agent/result/results_claude_20240617.md + ``` + +3. **对比不同 Agent 的表现** + ```bash + # 对比通过率、得分、常见错误等 + diff test/agent/result/results_claude_20240617.md \ + test/agent/result/results_gpt4_20240617.md + ``` + +--- + +## 📊 测试流程 + +### 1. 准备测试 + +```bash +# 查看测试用例 +cat test_cases.md + +# 选择要测试的 agent +AGENT="gpt4" # 或 claude, gemini, 等 +DATE=$(date +%Y%m%d) +``` + +### 2. 执行测试 + +对于每个测试用例： +1. 复制提示词（Prompt） +2. 发送给目标 agent +3. 记录生成的代码 +4. 根据评分标准打分（0/1/2） + +### 3. 保存结果 + +```bash +# 创建结果目录 +mkdir -p test/agent/result + +# 创建结果文件 +# 格式：result/results_{agent}_{YYYYMMDD}.md + +test/agent/result/results_gpt4_20240617.md +test/agent/result/results_claude_20240617.md +test/agent/result/results_gemini_20240617.md +``` + +### 4. 对比分析 + +```markdown +# 示例对比报告 + +| Agent | 测试日期 | 通过率 | 平均分 | 常见错误 | +|-------|---------|-------|--------|---------| +| Claude | 2026-06-10 | 100% (10/10) | 2.0 | 无 | +| GPT-4 | 2024-06-17 | 90% (9/10) | 1.8 | 赋值语法 | +| Gemini | 2024-06-17 | 85% (8.5/10) | 1.7 | 类定义 | +``` + +--- + +## 📝 结果文件命名规范 + +### 格式 + +``` +test/agent/result/results_{agent}_{YYYYMMDD}.md +``` + +**说明**： +- `result/`: 测试结果统一存放目录（已加入 `.gitignore`） +- `{agent}`: agent 名称（小写，如 claude, gpt4, gemini） +- `{YYYYMMDD}`: 测试日期（如 20240617） + +### 示例 + +``` +test/agent/result/results_claude_20260610.md # Claude 在 2026-06-10 的测试 +test/agent/result/results_claude_20240617.md # Claude 在 2024-06-17 的测试 +test/agent/result/results_gpt4_20240617.md # GPT-4 在 2024-06-17 的测试 +test/agent/result/results_gpt4o_20240617.md # GPT-4o 在 2024-06-17 的测试 +test/agent/result/results_gemini_20240617.md # Gemini 在 2024-06-17 的测试 +test/agent/result/results_gemini15_20240617.md # Gemini 1.5 在 2024-06-17 的测试 +``` + +--- + +## 🎯 .gitignore 配置 + +### 版本控制策略 + +**提交到 git**： +``` +✅ test/agent/test_cases.md # 测试定义（英文完整版） +✅ test/agent/test_cases_zh.md # 测试定义（中文完整版） +✅ test/agent/README.md # 说明文档 +``` + +**不提交**（已加入 `.gitignore`）： +``` +❌ test/agent/result/ # 测试结果目录 +``` + +--- + +## 📊 测试用例覆盖 + +`test_cases.md` 包含 100+ 测试用例，覆盖： + +| 语法点 | 测试用例数 | +|-------|----------| +| 函数定义 | 15+ | +| 类与对象 | 10+ | +| 控制流 | 10+ | +| 变量与赋值 | 8+ | +| Unit 模块 | 5+ | +| 参数传递 | 8+ | +| 类型系统 | 6+ | +| 错误边界 | 10+ | +| 其他 | 30+ | + +**总计**：100+ 测试用例 + +--- + +## 🔗 相关文档 + +### TSL 文档 +- TSL 语法文档：`docs/tsl/syntax/` +- TSL 快速索引：`docs/tsl/syntax/00_agent_index.json` +- TSL 语法入口：`docs/tsl/syntax/index.md` + +### Agent 优化 +- Agent 快速索引：`docs/tsl/syntax/00_agent_index.json` + - 为 agent 优化，减少 75% token 消耗 + - 包含精确行号和示例代码 + +--- + +## 💡 最佳实践 + +### 1. 保持测试定义的通用性 + +- ✅ 测试用例应该对所有 agent 都适用 +- ✅ 不要添加特定 agent 的专属测试 +- ✅ 关注 TSL 语法本身，而非 agent 特性 + +### 2. 结果命名规范 + +- ✅ 使用统一的命名格式 +- ✅ 包含 agent 名称和日期 +- ✅ 便于排序和查找 + +### 3. 定期对比 + +- 建议每季度测试一次所有 agent +- 追踪 agent 的改进趋势 +- 发现不同 agent 的优势和劣势 + +### 4. 基线管理 + +- 保留第一次测试结果作为基线 +- 新结果与基线对比 +- 追踪质量变化 + +--- + +## 🎉 示例：测试新 Agent + +### 步骤 + +```bash +# 1. 选择测试用例 +cat test_cases.md | grep "### TSL-001" + +# 2. 复制提示词发送给新 agent（如 GPT-4） + +# 3. 记录结果 +cat > results_gpt4_20240617.md << 'EOF' +# TSL Codegen Test Results - GPT-4 + +Date: 2024-06-17 +Agent: GPT-4 (gpt-4-turbo) + +## Summary +- Cases run: 10 +- Cases passed: 9 +- First-pass score: 18 / 20 +- Pass rate: 90% + +## Results +| Case | Score | Notes | +|------|-------|-------| +| TSL-001 | 2 | Correct | +| TSL-002 | 2 | Correct | +| TSL-003 | 1 | Minor issue | +... +EOF + +# 4. 对比 Claude 和 GPT-4 +diff results_claude_20260610.md results_gpt4_20240617.md +``` + +--- + +**维护者**：TSL Team +**最后更新**：2024-06-17 +**支持的 Agent**：所有支持 TSL 的 agent diff --git a/test/agent/test_cases.md b/test/agent/test_cases.md new file mode 100644 index 00000000..7335472e --- /dev/null +++ b/test/agent/test_cases.md @@ -0,0 +1,2218 @@ +# TSL Agent Codegen Prompt Tests + +This file defines manual prompt tests for evaluating whether an agent can read +`docs/tsl` and produce syntactically correct TSL code on the first attempt. + +These are not TSL language docs. They are agent evaluation prompts. Keep grammar +facts in `docs/tsl`; keep agent test prompts here. + +## How To Run + +For each case: + +1. Start from a fresh agent context that has access to this repository. +2. Send only the `Prompt` text to the agent unless the test runner has a + standard system prompt. +3. Allow the agent to read `docs/tsl`. +4. Score the first complete answer only. Do not let the agent revise. +5. Record pass/fail against the `Pass criteria`. + +Recommended runner setup: + +```text +You are in this repository. TSL grammar and reference docs are under docs/tsl. +When asked to write TSL, read the relevant docs/tsl pages first. Do not infer +syntax from Pascal, TypeScript, JavaScript, Python, or SQL. +``` + +## Scoring + +- `2` = first answer satisfies all pass criteria. +- `1` = mostly correct, but has one minor issue that does not change the tested + grammar point. +- `0` = wrong file model, invalid TSL syntax, invented syntax, or missed the + tested grammar point. + +Track these aggregate metrics: + +- Overall first-pass accuracy. +- Accuracy by topic group. +- Most common failure patterns. +- Whether failures came from not reading docs, reading the wrong docs page, or + overfitting to another language. + +## Global Failure Patterns + +Flag these as failures whenever they appear in generated code: + +- Uses `=` for ordinary assignment instead of `:=`. +- Uses comma separators in a typed parameter list, such as + `function Add(a: integer, b: integer): integer`. +- Writes named arguments as `a = 1` instead of `a: 1`. +- Writes a `.tsl` script as only top-level reusable declarations when executable + script behavior was requested. +- Appends executable script statements after a `.tsl` function or class + declaration section. +- Writes a top-level class as `class Name ... end;` instead of + `type Name = class ... end;`. +- Uses bare class names for class functions or static fields instead of + `class(Name)`. +- Invents syntax not documented in `docs/tsl`. + +## Test Cases + +### TSL-001: Typed Add Function + +Prompt: + +```text +请根据本仓库 docs/tsl 的语法，写一个 TSL 加法函数 Add。 +要求两个参数都有整数类型，返回值也要有整数类型。 +只输出代码。 +``` + +Expected focus: + +- Basic `function` declaration. +- Typed parameters and typed return value. + +Pass criteria: + +- Uses `function Add(a: integer; b: integer): integer;`. +- Uses `return a + b;`. +- Uses `begin ... end;`. +- Does not separate typed parameters with commas. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-002: Executable Script Calling A Local Function + +Prompt: + +```text +写一段可执行的 .tsl 脚本：计算 1 + 2，并用 writeLn 输出结果。 +加法逻辑封装成 Add 函数，脚本里调用它。 +只输出代码。 +``` + +Expected focus: + +- `.tsl` file model. +- Executable statements before local function declarations. + +Pass criteria: + +- Script statements appear before the `function Add...` declaration. +- Calls `writeLn(Add(1, 2));` or an equivalent statement before declarations. +- Does not append executable statements after the function declaration. +- Uses `:=` for ordinary assignments if assignments are introduced. + +Source docs: + +- `docs/tsl/syntax/01_quickstart.md` +- `docs/tsl/syntax/02_core_model.md` +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-003: Reusable Function File + +Prompt: + +```text +我要一个可复用的 .tsf 函数扩展文件，里面只有一个函数 IsPositive， +输入整数 x，返回 x 是否大于 0。只输出代码。 +``` + +Expected focus: + +- `.tsf` reusable declaration model. +- No executable script entry statements. + +Pass criteria: + +- Outputs a top-level `function IsPositive(x: integer);` or typed return variant + if supported by the chosen evidence. +- Function body returns `x > 0`. +- Does not add `.tsl` entry statements such as `writeLn(...)`. +- Does not invent an undocumented `boolean` return type. + +Source docs: + +- `docs/tsl/syntax/01_quickstart.md` +- `docs/tsl/syntax/02_core_model.md` +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-004: Procedure With Write-Back Parameter + +Prompt: + +```text +写一段 .tsl 脚本，定义一个过程 Bump，把传入变量加 1。 +脚本里先把 a 设为 1，调用 Bump(a)，再输出 a。只输出代码。 +``` + +Expected focus: + +- `procedure` only when explicitly requested. +- `var` parameter write-back. +- `.tsl` declaration section order. + +Pass criteria: + +- Uses `procedure Bump(var x);`. +- Assigns `a := 1;` before calling `Bump(a);`. +- Outputs `a` before the procedure declaration section. +- Does not put a return type on the `procedure` header. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` +- `docs/tsl/syntax/02_core_model.md` + +### TSL-005: Named Parameter Call + +Prompt: + +```text +写一个 TSL 示例，定义函数 MakePair(a, b)，返回 array(a, b)。 +调用时必须使用命名参数，把 b 传 20，把 a 传 10，并输出两个元素。 +只输出代码。 +``` + +Expected focus: + +- Named argument syntax. +- Array indexing. + +Pass criteria: + +- Calls the function with `MakePair(b: 20, a: 10)` or equivalent named argument + order. +- Does not use `MakePair(b = 20, a = 10)`. +- Reads array elements with zero-based array indexes. +- Keeps executable statements before the function declaration in `.tsl`. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` +- `docs/tsl/syntax/12_matrix_and_collections.md` + +### TSL-006: Default Variable Model + +Prompt: + +```text +写一段最简单的 TSL 脚本：把 3 赋给 a，把 4 赋给 b， +再输出 a * b。不要做多余声明。只输出代码。 +``` + +Expected focus: + +- Ordinary variables do not need a `var` declaration by default. +- Assignment operator. + +Pass criteria: + +- Uses `a := 3;` and `b := 4;`. +- Does not use `a = 3;` or `b = 4;`. +- Does not add unnecessary `var` declarations. + +Source docs: + +- `docs/tsl/syntax/04_variables_and_constants.md` +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-007: Explicit Variable Mode + +Prompt: + +```text +写一段 TSL 脚本，开启 explicit 模式，声明变量 total， +把 total 设置为 0，然后输出它。只输出代码。 +``` + +Expected focus: + +- `{$explicit+}`. +- Explicit `var` declaration. + +Pass criteria: + +- Starts with `{$explicit+}` or places it before first undeclared variable use. +- Declares `var total;`. +- Assigns with `total := 0;`. + +Source docs: + +- `docs/tsl/syntax/04_variables_and_constants.md` +- `docs/tsl/syntax/16_lexical_structure_and_compile_options.md` + +### TSL-008: Constant Initialization + +Prompt: + +```text +写一段 TSL 脚本，定义常量 max_count 为 3 + 4， +然后输出 max_count。只输出代码。 +``` + +Expected focus: + +- `const name = value;` is constant initialization, not ordinary assignment. + +Pass criteria: + +- Uses `const max_count = 3 + 4;`. +- Outputs `max_count`. +- Does not later assign to `max_count`. + +Source docs: + +- `docs/tsl/syntax/04_variables_and_constants.md` +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-009: Single-Variable Destructuring + +Prompt: + +```text +写一段 TSL 脚本，从 array(7, 8, 9) 里只拆出第一个值到 first， +然后输出 first。只输出代码。 +``` + +Expected focus: + +- Single-variable destructuring keeps the trailing comma. + +Pass criteria: + +- Uses `[first, ] := array(7, 8, 9);`. +- Does not use `[first] := ...`. + +Source docs: + +- `docs/tsl/syntax/04_variables_and_constants.md` +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-010: If Else Block + +Prompt: + +```text +写一段 TSL 脚本：如果 score >= 60，就把 result 设为 "pass"， +否则设为 "fail"，最后输出 result。score 设为 70。只输出代码。 +``` + +Expected focus: + +- Block-style `if ... then begin ... end else begin ... end`. +- No semicolon between `then` block `end` and `else`. + +Pass criteria: + +- Uses `if score >= 60 then` followed by a valid block. +- Does not put a semicolon after the `then` branch `end` before `else`. +- Outputs after the conditional block, not inside only one branch. + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-011: For Loop With Step + +Prompt: + +```text +写一段 TSL 脚本，用 for 循环计算 1、3、5 的和并输出。 +要求使用 step。只输出代码。 +``` + +Expected focus: + +- `for i := 1 to 5 step 2 do`. + +Pass criteria: + +- Uses `for i := 1 to 5 step 2 do`. +- Accumulates with `:=` or `+=`. +- Outputs `9` or the computed sum variable. + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-012: Array Traversal + +Prompt: + +```text +写一段 TSL 脚本，遍历 array(10, 20, 30)，每行输出索引和值的和。 +必须使用 for i, v in data。只输出代码。 +``` + +Expected focus: + +- Array traversal form. +- Zero-based index behavior. + +Pass criteria: + +- Uses `for i, v in data do`. +- Uses `data := array(10, 20, 30);`. +- Does not invent Python-style or JavaScript-style iteration syntax. + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-013: Array And String Indexing + +Prompt: + +```text +写一段 TSL 脚本，创建 array(10, 20, 30) 和字符串 "ABC"。 +输出数组第一个元素，再输出字符串第一个字符。只输出代码。 +``` + +Expected focus: + +- Arrays are zero-based. +- Strings are one-based. + +Pass criteria: + +- Reads the first array element with `arr[0]`. +- Reads the first string character with `s[1]`. +- Does not use `s[0]`. + +Source docs: + +- `docs/tsl/syntax/01_quickstart.md` +- `docs/tsl/syntax/03_values_and_literals.md` +- `docs/tsl/syntax/11_pitfalls.md` + +### TSL-014: Hash-Like Array + +Prompt: + +```text +写一段 TSL 脚本，用 array 创建一个带字符串键的表， +包含 Code = "0001" 和 Price = 12.3，然后输出 Code。只输出代码。 +``` + +Expected focus: + +- `array("Code": "0001", "Price": 12.3)`. + +Pass criteria: + +- Uses string-key `array(...)` syntax. +- Reads with `hash["Code"]` or equivalent variable name. + +Source docs: + +- `docs/tsl/syntax/12_matrix_and_collections.md` + +### TSL-015: in Versus sqlin + +Prompt: + +```text +写一段 TSL 脚本，同时演示： +1 是否属于 array(1, 2)，以及 array(1, 2) 这一整行是否存在于 +array((1, 2), (3, 4))。分别输出两个判断结果。只输出代码。 +``` + +Expected focus: + +- Element/subset relation uses `in`. +- Whole-row relation uses `sqlin`. + +Pass criteria: + +- Uses `1 in array(1, 2)`. +- Uses `array(1, 2) sqlin array((1, 2), (3, 4))`. +- Does not use `in` for the whole-row test. + +Source docs: + +- `docs/tsl/syntax/12_matrix_and_collections.md` + +### TSL-016: Explicit String To Integer Conversion + +Prompt: + +```text +写一段 TSL 脚本，把字符串 "1234" 转成整数后加 1， +再输出结果。只输出代码。 +``` + +Expected focus: + +- Explicit conversion instead of relying on mixed-type arithmetic. + +Pass criteria: + +- Uses `strToInt(...)`. +- Does not directly compute `"1234" + 1`. + +Source docs: + +- `docs/tsl/syntax/17_types_and_conversions.md` + +### TSL-017: Nil Handling + +Prompt: + +```text +写一段 TSL 脚本，创建空数组 arr，判断 arr[0] 是否为 nil， +并输出判断结果。只输出代码。 +``` + +Expected focus: + +- Empty array missing element returns `nil`. +- Explicit nil comparison. + +Pass criteria: + +- Uses `arr := array();`. +- Checks `arr[0] = nil` or uses documented `ifNil(...)`. +- Does not invent `null`, `None`, or `undefined`. + +Source docs: + +- `docs/tsl/syntax/17_types_and_conversions.md` + +### TSL-018: Regex-Like + +Prompt: + +```text +写一段 TSL 脚本，判断字符串 "abc" 是否匹配以 a 开头的模式， +用 like 运算符，并输出结果。只输出代码。 +``` + +Expected focus: + +- `like` right side is regex-like, not SQL `%` wildcard. + +Pass criteria: + +- Uses a regex-style pattern such as `"^a.*"` or another documented-compatible + regex pattern. +- Does not use `"a%"` as the pattern. + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` +- `docs/tsl/syntax/11_pitfalls.md` + +### TSL-019: Basic Class + +Prompt: + +```text +写一段 .tsl 脚本，定义 Person 类，包含 public 字段 name。 +脚本里创建 Person，把 name 设为 "Tom"，然后输出 name。只输出代码。 +``` + +Expected focus: + +- Top-level class declaration syntax. +- `.tsl` executable statements before class declaration section. + +Pass criteria: + +- Uses `type Person = class`. +- Includes `public` before `name;`. +- Creates with `new Person()`. +- Does not write `class Person`. +- Does not append executable statements after the class declaration. + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` +- `docs/tsl/syntax/02_core_model.md` + +### TSL-020: Public Constructor + +Prompt: + +```text +写一段 .tsl 脚本，定义 Counter 类。 +构造函数接收初始值 v，保存到 value；Inc 方法把 value 加 1 并返回。 +脚本里 new Counter(10)，输出 Inc 的结果。只输出代码。 +``` + +Expected focus: + +- `function create(...)` constructor under `public`. +- Instance method body accesses members directly. + +Pass criteria: + +- Defines `type Counter = class`. +- Puts `function create(v);` in a `public` section. +- Uses `value := v;` in `create`. +- Uses `value := value + 1; return value;` or equivalent in `Inc`. +- Does not make `create` private or protected. + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-021: Static Field Access + +Prompt: + +```text +写一段 TSL 示例，定义 THuman 类，包含 static 字段 mCount。 +先把 mCount 设置为 100，再输出它。只输出代码。 +``` + +Expected focus: + +- Static field access through class type. + +Pass criteria: + +- Defines `static mCount;`. +- Sets or reads it through `class(THuman).mCount`. +- Does not use `THuman.mCount`. + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` +- `docs/tsl/syntax/11_pitfalls.md` + +### TSL-022: Class Function Access + +Prompt: + +```text +写一个 TSL 类 MathBox，里面有 class function Add(a, b)，返回 a + b。 +再写脚本输出 MathBox 的 Add(1, 2) 结果。只输出代码。 +``` + +Expected focus: + +- Class function declaration. +- Class function call through class type. + +Pass criteria: + +- Defines a `class function Add(a, b);` inside `type MathBox = class`. +- Calls via `class(MathBox).Add(1, 2)` or another documented class-type path. +- Does not call `MathBox.Add(1, 2)`. +- Keeps executable call before the class declaration in `.tsl`. + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` +- `docs/tsl/syntax/11_pitfalls.md` + +### TSL-023: Full Unit Skeleton + +Prompt: + +```text +写一个 .tsf unit，名字是 DemoUnit。 +对外暴露函数 Ping，调用返回 1。使用完整 interface / implementation 结构。 +只输出代码。 +``` + +Expected focus: + +- Full `unit` structure. +- `end.` terminator. + +Pass criteria: + +- Starts with `unit DemoUnit;`. +- Has `interface` and `implementation` sections. +- Declares `function Ping();` in `interface`. +- Implements `function Ping(); begin return 1; end;`. +- Ends the unit with `end.`. + +Source docs: + +- `docs/tsl/syntax/09_units_and_scope.md` +- `docs/tsl/syntax/01_quickstart.md` + +### TSL-024: Top-Level uses Before Statements + +Prompt: + +```text +写一段 .tsl 脚本，使用 UnitA 和 UnitB 两个 unit， +然后调用 Run() 并输出结果。注意 uses 的位置。只输出代码。 +``` + +Expected focus: + +- Top-level `uses` before ordinary statements. +- Multiple units in one `uses` statement. + +Pass criteria: + +- Uses `uses UnitA, UnitB;` before executable statements. +- Does not write ordinary statements before top-level `uses`. +- Does not generate two separate top-level `uses` statements as the default. + +Source docs: + +- `docs/tsl/syntax/09_units_and_scope.md` +- `docs/tsl/syntax/11_pitfalls.md` + +### TSL-025: Function-Body uses Placement + +Prompt: + +```text +写一个 TSL 函数 RunInFunction，函数体内使用 DemoUnit， +然后返回 Ping()。只输出这个函数代码。 +``` + +Expected focus: + +- Function-body `uses` must be the first statement. + +Pass criteria: + +- Writes `uses DemoUnit;` as the first statement after `begin`. +- Does not put any assignment or other statement before function-body `uses`. +- Does not repeat `uses` inside the same function body. + +Source docs: + +- `docs/tsl/syntax/09_units_and_scope.md` + +### TSL-026: Try Except + +Prompt: + +```text +写一段 TSL 脚本，用 try/except 捕获 raise "bad"， +在 except 中输出 exceptObject.errInfo。只输出代码。 +``` + +Expected focus: + +- TSL exception syntax. +- `exceptObject` fields. + +Pass criteria: + +- Uses `try ... except ... end`. +- Raises with `raise "bad"`. +- Reads `exceptObject.errInfo` in the `except` block. + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-027: Ambiguous File Model + +Prompt: + +```text +帮我写一个 TSL 的加法函数。 +``` + +Expected focus: + +- Handling an underspecified user request. +- Avoiding invented file model assumptions. + +Pass criteria: + +- Either produces only a minimal reusable function declaration, or explicitly + states the file-model assumption before the code. +- Uses `function`, not `procedure`. +- Does not generate invalid `.tsl` declaration ordering. +- Does not invent parameter types if the prompt did not require them. + +Source docs: + +- `docs/tsl/index.md` +- `docs/tsl/syntax/01_quickstart.md` +- `docs/tsl/syntax/02_core_model.md` +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-028: Bad Prompt With Type Requirement + +Prompt: + +```text +帮我写一个tsl代码，写一个加法，需要参数类型和返回类型。 +``` + +Expected focus: + +- Robustness to informal Chinese prompts. +- Correct typed function syntax. + +Pass criteria: + +- Uses a `function` with typed parameters and typed return value. +- Uses semicolons between typed parameters. +- Uses `return a + b;`. +- Does not use TypeScript-like syntax such as + `function add(a: number, b: number): number`. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-029: Anti-Pascal Assignment Trap + +Prompt: + +```text +写一段 TSL 脚本，把 a 设为 1，把 b 设为 2， +如果 a + b 等于 3 就输出 "ok"。只输出代码。 +``` + +Expected focus: + +- Ordinary assignment versus equality comparison. + +Pass criteria: + +- Uses `a := 1;` and `b := 2;`. +- Uses `=` only in the comparison expression. +- Does not use `==`. + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` +- `docs/tsl/syntax/11_pitfalls.md` + +### TSL-030: No Script After Declaration Trap + +Prompt: + +```text +写一段 .tsl 脚本：先调用 Hello()，Hello 输出 "hello"。 +调用完成后再输出 "done"。只输出代码。 +``` + +Expected focus: + +- All executable script statements must be before the declaration section. +- A natural prompt order can tempt the agent to put `writeLn("done")` after + `function Hello`. + +Pass criteria: + +- Places both `Hello();` and the statement that outputs `"done"` before + `function Hello();`. +- Defines `Hello` after the executable statements. +- Does not append the `"done"` output statement after the function declaration. + +Source docs: + +- `docs/tsl/syntax/01_quickstart.md` +- `docs/tsl/syntax/02_core_model.md` +- `docs/tsl/syntax/11_pitfalls.md` + +## Extended Compact Cases + +The first 30 cases above are detailed baseline cases. The following compact +cases broaden grammar coverage while keeping each prompt independently runnable. + +### TSL-031: Numeric Literal Types + +Prompt: + +```text +写一段 TSL 脚本，分别输出 0x10、0b10、0o10、100L、1E2 的类型判断结果。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented numeric literals. +- Uses type checks such as `ifInt`, `ifInt64`, and `ifReal`. +- Does not rewrite the literals into decimal-only values. + +Source docs: + +- `docs/tsl/syntax/17_types_and_conversions.md` + +### TSL-032: Date Time Literals + +Prompt: + +```text +写一段 TSL 脚本，创建 20111231T 和 20101231.0931T， +并分别输出日期和时间字符串。只输出代码。 +``` + +Pass criteria: + +- Uses documented date-time literal forms. +- Uses documented conversion helpers such as `dateToStr` and `timeToStr`. +- Does not invent ISO string literal syntax. + +Source docs: + +- `docs/tsl/syntax/17_types_and_conversions.md` + +### TSL-033: Boolean And Numeric Truthiness + +Prompt: + +```text +写一段 TSL 脚本，输出 true、false，并演示 if 2、if 0、if -1 的判断结果。 +只输出代码。 +``` + +Pass criteria: + +- Uses `true` and `false` directly. +- Treats `0` as false and non-zero numeric values as true. +- Does not invent `True` / `False` capitalization. + +Source docs: + +- `docs/tsl/syntax/17_types_and_conversions.md` + +### TSL-034: Nil Arithmetic Boundary + +Prompt: + +```text +写一段 TSL 脚本，输出 ifNil(nil)、nil + 1、1 + nil， +以及 nil + nil 是否仍为 nil。只输出代码。 +``` + +Pass criteria: + +- Uses `nil`, not `null`, `None`, or `undefined`. +- Uses `ifNil(nil)` or documented `nil` comparison. +- Does not reject `nil + 1` as invalid syntax. + +Source docs: + +- `docs/tsl/syntax/17_types_and_conversions.md` + +### TSL-035: Complex Number Basics + +Prompt: + +```text +写一段 TSL 脚本，创建复数 4 + 3j 和 complex(5, -2)， +输出第一个复数的 real、imag 和 ifComplex 判断。只输出代码。 +``` + +Pass criteria: + +- Uses `4 + 3j` or `complex(real, imag)` as documented. +- Uses `real(...)`, `imag(...)`, and `ifComplex(...)`. +- Does not invent Python object methods such as `.real`. + +Source docs: + +- `docs/tsl/syntax/17_types_and_conversions.md` + +### TSL-036: String Concatenation + +Prompt: + +```text +写一段 TSL 脚本，把 "TS" 和 "L" 拼成 "TSL" 并输出。 +使用 docs/tsl 里确认的字符串连接写法。只输出代码。 +``` + +Pass criteria: + +- Uses documented string concatenation with `+` or `$`. +- Uses TSL string literals. +- Does not call undocumented helpers such as `concat(...)`. + +Source docs: + +- `docs/tsl/syntax/03_values_and_literals.md` +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-037: Arithmetic Operator Coverage + +Prompt: + +```text +写一段 TSL 脚本，分别输出 9 div 4、9 mod 4、2 ^ 3、8 ~ 2、3 \ 2。 +只输出代码。 +``` + +Pass criteria: + +- Uses `div`, `mod`, `^`, `~`, and `\` as documented. +- Does not replace them with JavaScript-style operators. + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-038: Conditional Expression + +Prompt: + +```text +写一段 TSL 脚本，a 小于 b 时 value 为 10，否则为 20， +要求使用条件表达式并输出 value。只输出代码。 +``` + +Pass criteria: + +- Uses `condition ? true_value : false_value`. +- Uses `:=` for assignments. +- Does not invent `?:` placement from C/JS incorrectly. + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-039: Omitted-True Conditional Expression + +Prompt: + +```text +写一段 TSL 脚本，分别输出 2 ?: 9 和 0 ?: 9 的结果。只输出代码。 +``` + +Pass criteria: + +- Uses the documented `value ?: fallback` form. +- Does not rewrite it as a normal `if` statement unless it preserves the tested + expression form. + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-040: Logical Operators + +Prompt: + +```text +写一段 TSL 脚本，使用 and、or、not 组合两个条件，并输出结果。 +只输出代码。 +``` + +Pass criteria: + +- Uses `and`, `or`, and `not`. +- Does not use `!` as logical negation. + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-041: Bitwise Operators + +Prompt: + +```text +写一段 TSL 脚本，对两个整数演示位与、位或、位非、位异或， +并输出结果。只输出代码。 +``` + +Pass criteria: + +- Uses dot-prefixed bitwise operators such as `.&`, `.|`, `.!`, and `.^`. +- Does not use ordinary `&`, `|`, or `~` as bitwise operators. + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-042: Compound Assignment And Increment + +Prompt: + +```text +写一段 TSL 脚本，a 初始为 1，先用复合赋值加 2， +再自增一次，最后输出 a。只输出代码。 +``` + +Pass criteria: + +- Uses documented `+=` and `a++` or `++a`. +- Initializes with `a := 1;`. +- Does not use `a = a + 2`. + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-043: Nil-Safe Access + +Prompt: + +```text +写一段 TSL 示例，安全读取可能为 nil 的对象成员 value， +使用 docs/tsl 里的空安全访问写法。只输出代码。 +``` + +Pass criteria: + +- Uses documented nil-safe access such as `obj?.value`. +- Does not invent optional chaining forms beyond the documented patterns. + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-044: Scalar Chain Comparison + +Prompt: + +```text +写一段 TSL 脚本，判断 1 < 2 < 3 的连续标量比较并输出结果。 +使用 docs/tsl 的链式比较写法。只输出代码。 +``` + +Pass criteria: + +- Uses scalar chain comparison such as `1 :< 2 :< 3`. +- Does not write Python-style `1 < 2 < 3`. + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-045: Matrix-Like Chain Comparison + +Prompt: + +```text +写一段 TSL 脚本，对 array(1, 2, -1)、array(2, 1, 0)、array(3, 2, 1) +做逐元素链式小于比较，并输出结果数组的三个元素。只输出代码。 +``` + +Pass criteria: + +- Uses matrix chain comparison such as `::<`. +- Reads result array elements by zero-based indexes. +- Does not use scalar `:<` for array-wise comparison. + +Source docs: + +- `docs/tsl/syntax/12_matrix_and_collections.md` +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-046: Default Parameter + +Prompt: + +```text +写一个 TSL 函数 AddOne，参数 a 默认值为 1，返回 a + 1。 +再写脚本输出 AddOne() 和 AddOne(5)。只输出代码。 +``` + +Pass criteria: + +- Uses `function AddOne(a = 1);`. +- Calls the function before the `.tsl` declaration section. +- Does not use unsupported default-parameter syntax. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-047: Typed Default Parameter + +Prompt: + +```text +写一个 TSL 函数 TypedAdd，参数 a 是 integer，默认值为 1， +返回值是 integer，返回 a + 1。只输出代码。 +``` + +Pass criteria: + +- Uses `function TypedAdd(a: integer = 1): integer;`. +- Does not separate typed parameters with commas. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-048: Named Parameter Skipping Middle Argument + +Prompt: + +```text +写一段 TSL 脚本，定义 TestFunc(a, b, c)，调用 TestFunc(1, c: 3)， +在函数里输出 b 是否为 nil。只输出代码。 +``` + +Pass criteria: + +- Uses named parameter syntax `c: 3`. +- Checks skipped `b` with `ifNil(b)` or documented nil comparison. +- Keeps executable call before the function declaration. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-049: call With Named Parameters + +Prompt: + +```text +写一段 TSL 脚本，通过 call 调用 TestFunc，并用命名参数传 a、b、c。 +TestFunc 返回 a * 100 + b * 10 + c。只输出代码。 +``` + +Pass criteria: + +- Uses `call("TestFunc", a: ..., b: ..., c: ...)`. +- Does not write named arguments with `=`. +- Defines `TestFunc` after the call in `.tsl`. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-050: varByRef Switch + +Prompt: + +```text +写一段 TSL 脚本，演示 {$varByRef-} 下未修饰参数不写回， +但 var 参数仍会写回。只输出代码。 +``` + +Pass criteria: + +- Uses `{$varByRef-}` and later restores if needed with `{$varByRef+}`. +- Includes one unmodified parameter function and one `var` parameter function. +- Does not rely on another language's value/reference model. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` +- `docs/tsl/syntax/16_lexical_structure_and_compile_options.md` + +### TSL-051: in And out Call Prefixes + +Prompt: + +```text +写一段 TSL 脚本，在 {$varByRef-} 下调用 Touch3(in a, out b, c)， +演示只有 b 被写回。只输出代码。 +``` + +Pass criteria: + +- Uses call-site prefixes `in` and `out`. +- Uses `{$varByRef-}`. +- Does not write `in` / `out` as type annotations in the function header. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-052: exit Boundary + +Prompt: + +```text +写一段 TSL 脚本，函数 Demo(x) 在 x > 0 时 exit， +否则 return 99；输出 Demo(1) 和 Demo(0)。只输出代码。 +``` + +Pass criteria: + +- Uses `exit;` inside the function. +- Uses `return 99;` for the other branch. +- Does not treat `exit` as returning an explicit custom value. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-053: Variadic Sum + +Prompt: + +```text +写一个 TSL 可变参数函数 SumAll(...)，遍历 Params 求和并返回。 +再输出 SumAll(1, 2, 3, 4)。只输出代码。 +``` + +Pass criteria: + +- Uses `function SumAll(...);`. +- Iterates `Params`. +- Does not invent JavaScript rest syntax. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-054: ParamCount And RealParamCount + +Prompt: + +```text +写一个 TSL 函数 CountArgs(a, b, ...)，返回 ParamCount * 10 + RealParamCount。 +输出 CountArgs(1, 2, 3, 4)。只输出代码。 +``` + +Pass criteria: + +- Uses `ParamCount` and `RealParamCount`. +- Uses trailing `...` in the function header. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-055: Variadic Forward With call + +Prompt: + +```text +写一段 TSL 脚本，DoFunc(fc, ...) 通过 call(fc, ...) 转发参数给 Sum3。 +输出 DoFunc("Sum3", 1, 2, 3)。只输出代码。 +``` + +Pass criteria: + +- Uses `call(fc, ...)`. +- Uses `function DoFunc(fc, ...);`. +- Does not manually unpack a fixed number of variadic arguments. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-056: Anonymous Function Variable + +Prompt: + +```text +写一段 TSL 脚本，把匿名函数赋给变量 a， +匿名函数返回 x + y，然后用 call(a, 1, 2) 输出结果。只输出代码。 +``` + +Pass criteria: + +- Uses `a := function(x, y) begin ... end;`. +- Calls via `call(a, 1, 2)` or documented `##a(...)`. +- Does not call the function variable only as `a(1, 2)`. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-057: Anonymous Function As Argument + +Prompt: + +```text +写一段 TSL 脚本，定义 Apply(fun)，内部 call(fun, 2, 3)。 +调用 Apply 时直接传入一个匿名乘法函数。只输出代码。 +``` + +Pass criteria: + +- Passes `function(x, y) begin ... end` as an argument. +- Uses `call(fun, 2, 3)` inside `Apply`. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-058: findFunction Call + +Prompt: + +```text +写一段 TSL 脚本，用 findFunction("Add") 找到 Add 函数， +再用文档支持的函数值调用方式输出 Add(1, 2)。只输出代码。 +``` + +Pass criteria: + +- Uses `findFunction("Add")`. +- Calls the returned function with `##f(...)` or `call(f, ...)`. +- Does not call `f(...)` directly. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-059: thisFunction Call + +Prompt: + +```text +写一段 TSL 脚本，用 thisFunction(Add) 得到函数值， +再通过一个 Call 包装函数调用它。只输出代码。 +``` + +Pass criteria: + +- Uses `thisFunction(Add)`. +- Calls the function value with `call(...)` or documented wrapper style. +- Does not quote `Add` if using `thisFunction`. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-060: Global Function Qualification + +Prompt: + +```text +写一段 TSL 示例，局部函数名和全局/系统函数同名时， +用 docs/tsl 里明确的全局函数限定调用写法。只输出代码。 +``` + +Pass criteria: + +- Uses `::FuncName(...)` for global/system function qualification. +- Does not invent namespace separators from other languages. + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-061: Case Statement With Range + +Prompt: + +```text +写一段 TSL 脚本，a 为 4，用 case 判断： +1,2 输出 small；3 到 5 输出 mid；其他输出 other。只输出代码。 +``` + +Pass criteria: + +- Uses `case a of`. +- Uses comma labels and `3 to 5`. +- Uses `else` and closes with `end`. + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-062: Case Expression + +Prompt: + +```text +写一段 TSL 脚本，用 case 表达式给 value 赋值， +a 为 2 时 value 是 "two"，否则是 "other"，然后输出 value。只输出代码。 +``` + +Pass criteria: + +- Uses `value := case ... of ... else ... end;`. +- Does not put `begin ... end` blocks inside expression-form branches. + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-063: Repeat Until + +Prompt: + +```text +写一段 TSL 脚本，用 repeat ... until 把 counter 从 3 减到 0， +最后输出 counter。只输出代码。 +``` + +Pass criteria: + +- Uses `repeat ... until counter = 0;`. +- Does not write `do while` syntax. + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-064: Break In While Loop + +Prompt: + +```text +写一段 TSL 脚本，用 while true 循环累加 1 到 3， +i 大于 3 时 break，然后输出 sum。只输出代码。 +``` + +Pass criteria: + +- Uses `while true do`. +- Uses `break;` inside the loop. +- Uses TSL block structure for multi-statement loop body. + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-065: Continue In While Loop + +Prompt: + +```text +写一段 TSL 脚本，while 循环 i 从 1 到 4， +跳过 i = 2，只累加其他值并输出 sum。只输出代码。 +``` + +Pass criteria: + +- Uses `continue;` for the skipped iteration. +- Does not put the increment after a `continue` path that would cause an + infinite loop. + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-066: Try Finally + +Prompt: + +```text +写一段 TSL 脚本，用 try/finally，try 中输出 "run"， +finally 中输出 "cleanup"。只输出代码。 +``` + +Pass criteria: + +- Uses `try ... finally ... end`. +- Does not use `catch` or JavaScript-style exception syntax. + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-067: Exception Metadata + +Prompt: + +```text +写一段 TSL 脚本，raise "bad" 后在 except 中输出 errInfo、errLine、errNo。 +只输出代码。 +``` + +Pass criteria: + +- Uses `exceptObject.errInfo`, `exceptObject.errLine`, and `exceptObject.errNo`. +- Uses `try ... except ... end`. + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-068: Nested Array Destructuring + +Prompt: + +```text +写一段 TSL 脚本，从 array((1, 2), (3, 4)) 拆出 r1 和 r2， +并输出 r1[0]、r1[1]、r2[0]、r2[1]。只输出代码。 +``` + +Pass criteria: + +- Uses `[r1, r2] := array((1, 2), (3, 4));`. +- Reads nested array elements with zero-based indexes. + +Source docs: + +- `docs/tsl/syntax/04_variables_and_constants.md` +- `docs/tsl/syntax/12_matrix_and_collections.md` + +### TSL-069: Row Set Operations + +Prompt: + +```text +写一段 TSL 脚本，对 left_rows 和 right_rows 做 union2、intersect、minus、outersect。 +只输出代码。 +``` + +Pass criteria: + +- Uses row-set operators `union2`, `intersect`, `minus`, and `outersect`. +- Does not treat `union2` as preserving duplicate rows. + +Source docs: + +- `docs/tsl/syntax/12_matrix_and_collections.md` + +### TSL-070: filterIn Single Column + +Prompt: + +```text +写一段 TSL 示例，用 filterIn 按单列从结果集中筛选命中行。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented `filterIn(...)` shape. +- Does not replace resultset filtering with `in`/`sqlin` set operations. + +Source docs: + +- `docs/tsl/syntax/13_resultset_and_filters.md` + +### TSL-071: filterNotIn + +Prompt: + +```text +写一段 TSL 示例，用 filterNotIn 从结果集中排除命中行。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented `filterNotIn(...)` shape. +- Does not use `minus` when the task asks to preserve filtering semantics. + +Source docs: + +- `docs/tsl/syntax/13_resultset_and_filters.md` + +### TSL-072: TS-SQL Minimal Query + +Prompt: + +```text +写一段 TSL 示例，对 array((1, 2), (3, 4)) 使用 TS-SQL 最小查询骨架。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented TS-SQL query form from the syntax docs. +- Does not invent ordinary SQL string execution. + +Source docs: + +- `docs/tsl/syntax/14_ts_sql.md` + +### TSL-073: TS-SQL where And order by + +Prompt: + +```text +写一段 TSL 示例，使用 TS-SQL 对数组结果集按条件过滤并排序。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented `where` and `order by` TS-SQL syntax. +- Does not use SQL `%` wildcard assumptions unless documented for TS-SQL. + +Source docs: + +- `docs/tsl/syntax/14_ts_sql.md` + +### TSL-074: TS-SQL group by + +Prompt: + +```text +写一段 TSL 示例，使用 TS-SQL 按字段 group by，并计算每组统计值。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented `group by` TS-SQL form. +- Uses documented aggregate/reference helpers only. + +Source docs: + +- `docs/tsl/syntax/14_ts_sql.md` + +### TSL-075: TS-SQL join + +Prompt: + +```text +写一段 TSL 示例，用 TS-SQL join 两个数组结果集。只输出代码。 +``` + +Pass criteria: + +- Uses documented `join` form. +- Does not invent database connection or external SQL execution. + +Source docs: + +- `docs/tsl/syntax/14_ts_sql.md` + +### TSL-076: Runtime with Star + +Prompt: + +```text +写一段 TSL 示例，使用 docs/tsl 中的 with * 块环境写法。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented `with *` syntax. +- Does not invent Python `with` semantics. + +Source docs: + +- `docs/tsl/syntax/10_runtime_context_and_with.md` + +### TSL-077: Runtime with Double Star + +Prompt: + +```text +写一段 TSL 示例，使用 docs/tsl 中的 with ** 块环境写法。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented `with **` syntax. +- Does not generalize beyond the documented runtime context form. + +Source docs: + +- `docs/tsl/syntax/10_runtime_context_and_with.md` + +### TSL-078: Grid Call Timeout + +Prompt: + +```text +写一段 TSL 示例，用 # 网格调用并带 timeout。只输出代码。 +``` + +Pass criteria: + +- Uses documented `#Func(...)` and `timeout N` shape. +- Does not turn `timeout` into a normal function argument unless documented. + +Source docs: + +- `docs/tsl/syntax/10_runtime_context_and_with.md` + +### TSL-079: Global Cache + +Prompt: + +```text +写一段 TSL 示例，设置全局缓存、读取全局缓存，并判断缓存是否存在。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented `setGlobalCache`, `getGlobalCache`, and `ifCache`. +- Does not invent browser/local-storage style APIs. + +Source docs: + +- `docs/tsl/syntax/10_runtime_context_and_with.md` + +### TSL-080: Conditional Compilation + +Prompt: + +```text +写一段 TSL 示例，使用 {$ifdef ...} 和 {$else} 做条件编译分支。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented compile-option syntax. +- Does not write runtime `if` when the task asks for conditional compilation. + +Source docs: + +- `docs/tsl/syntax/16_lexical_structure_and_compile_options.md` + +### TSL-081: Comments And Identifiers + +Prompt: + +```text +写一段 TSL 示例，包含 docs/tsl 支持的注释写法和一个普通标识符赋值。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented comment syntax from the lexical structure page. +- Uses `:=` for assignment. + +Source docs: + +- `docs/tsl/syntax/16_lexical_structure_and_compile_options.md` + +### TSL-082: goto Label + +Prompt: + +```text +写一段 TSL 示例，使用 goto 跳转到标签并输出结果。只输出代码。 +``` + +Pass criteria: + +- Uses documented `goto` and label syntax. +- Does not invent C-style label rules if they differ from docs. + +Source docs: + +- `docs/tsl/syntax/15_debug_and_profiler.md` + +### TSL-083: debugReturn + +Prompt: + +```text +写一段 TSL 示例，使用 debugReturn 提前返回调试值。只输出代码。 +``` + +Pass criteria: + +- Uses documented `debugReturn` form. +- Does not confuse it with ordinary `return` unless both are required. + +Source docs: + +- `docs/tsl/syntax/15_debug_and_profiler.md` + +### TSL-084: Profiler Timing + +Prompt: + +```text +写一段 TSL 示例，使用 mtic 和 mtoc 做简单计时。只输出代码。 +``` + +Pass criteria: + +- Uses documented `mtic` / `mtoc` shape. +- Does not invent external timing APIs. + +Source docs: + +- `docs/tsl/syntax/15_debug_and_profiler.md` + +### TSL-085: External Function Declaration + +Prompt: + +```text +写一个 TSL external 函数声明示例，按 docs/tsl 的最小 external 写法。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented `external` declaration shape. +- Does not invent FFI syntax from C, Python, or TypeScript. + +Source docs: + +- `docs/tsl/syntax/18_external_calls_and_threads.md` + +### TSL-086: External Procedure Declaration + +Prompt: + +```text +写一个 TSL procedure external 示例。只输出代码。 +``` + +Pass criteria: + +- Uses documented `procedure external` shape. +- Does not put a return type on the procedure header. + +Source docs: + +- `docs/tsl/syntax/18_external_calls_and_threads.md` + +### TSL-087: Native Function Pointer Wrapper + +Prompt: + +```text +写一段 TSL 示例，按 docs/tsl 包装原生函数指针。只输出代码。 +``` + +Pass criteria: + +- Uses only the documented native-function-pointer wrapper shape. +- Does not invent raw pointer syntax. + +Source docs: + +- `docs/tsl/syntax/18_external_calls_and_threads.md` + +### TSL-088: Thread Minimal Pattern + +Prompt: + +```text +写一段 TSL 线程模式最小正例，按 docs/tsl 的线程示例组织。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented thread-mode syntax. +- Does not invent async/await or JavaScript thread syntax. + +Source docs: + +- `docs/tsl/syntax/18_external_calls_and_threads.md` + +### TSL-089: Class Property + +Prompt: + +```text +写一个 TSL 类 Box，字段 value 通过 property Value read/write 访问。 +脚本里设置并输出这个属性。只输出代码。 +``` + +Pass criteria: + +- Uses documented `property Name read ... write ...` shape. +- Uses `type Box = class`. +- Creates with `new Box()`. + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-090: Typed Class Property + +Prompt: + +```text +写一个 TSL 类 Person，包含 string 类型字段 name_， +并定义带类型注解的 property Name。只输出代码。 +``` + +Pass criteria: + +- Uses field type annotation such as `name_: string;`. +- Uses documented typed property form. +- Does not invent C# property blocks. + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-091: Method Overload + +Prompt: + +```text +写一个 TSL 类 Calc，包含两个同名 Add 方法，参数个数不同。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented `overload` method form. +- Keeps methods inside `type Calc = class`. + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-092: Inheritance + +Prompt: + +```text +写一个 TSL 类 Animal 和继承它的 Dog，Dog 增加一个方法 Speak。 +只输出代码。 +``` + +Pass criteria: + +- Uses `type Dog = class(Animal)`. +- Does not use `extends`. + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-093: Virtual Override + +Prompt: + +```text +写一个 TSL 父类 Base，虚方法 Name；子类 Child 覆盖 Name。 +脚本里创建 Child 并输出 Name。只输出代码。 +``` + +Pass criteria: + +- Uses documented `virtual` and `override`. +- Uses `type Child = class(Base)`. +- Creates with `new Child()`. + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-094: Inherited Method Call + +Prompt: + +```text +写一个 TSL 子类方法，在方法里调用父类同名方法后再追加自己的逻辑。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented `Inherited` call form. +- Does not invent `super.method()` syntax. + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-095: Class Method Implementation Outside Class + +Prompt: + +```text +写一个 TSL 类 Greeter，类内只声明 Say 方法， +在类外用 ClassName.Method 形式实现它。只输出代码。 +``` + +Pass criteria: + +- Uses class declaration plus `function Greeter.Say(...)` implementation. +- Does not append executable script statements after the implementation section. + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-096: createObject By String Class Name + +Prompt: + +```text +写一段 TSL 示例，用字符串类名通过 createObject 创建本地类实例。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented `createObject("ClassName")` shape. +- Uses `new ClassName()` only if explaining it is not the requested string-name + path. + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-097: Destructor + +Prompt: + +```text +写一个 TSL 类，定义无参 destroy 函数，在对象引用设为 nil 时触发清理。 +只输出代码。 +``` + +Pass criteria: + +- Uses `function destroy();`. +- Sets the object reference to `nil` in executable script code. +- Does not invent `destructor` keyword. + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-098: FMArray Basics + +Prompt: + +```text +写一段 TSL 示例，创建 FMArray，判断它是 FMArray，并输出尺寸信息。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented FMArray construction from the FMArray page. +- Uses documented FMArray type/size helpers. +- Does not treat plain `array(...)` as automatically being FMArray. + +Source docs: + +- `docs/tsl/syntax/23_fmarray.md` + +### TSL-099: Matrix Deep Dive + +Prompt: + +```text +写一段 TSL 示例，初始化矩阵并使用 mrows、mcols、msize 输出维度。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented matrix initialization. +- Uses `mrows`, `mcols`, and `msize`. + +Source docs: + +- `docs/tsl/syntax/22_matrix_deep_dive.md` + +### TSL-100: Object Operator Overload + +Prompt: + +```text +写一个 TSL 类，重载二元 + 运算符，让两个对象相加得到一个新对象。 +只输出代码。 +``` + +Pass criteria: + +- Uses documented `operator +` overload shape. +- Keeps overload implementation inside a valid `type Name = class` structure. +- Does not invent Python `__add__` or C++ syntax. + +Source docs: + +- `docs/tsl/syntax/24_object_overloads_and_iteration.md` + +## Result Sheet Template + +Copy this table for each evaluated agent: + +| Case | Score | Failure pattern | Notes | +| ------- | ----: | --------------- | ----- | +| TSL-001 | | | | +| TSL-002 | | | | +| TSL-003 | | | | +| TSL-004 | | | | +| TSL-005 | | | | +| TSL-006 | | | | +| TSL-007 | | | | +| TSL-008 | | | | +| TSL-009 | | | | +| TSL-010 | | | | +| TSL-011 | | | | +| TSL-012 | | | | +| TSL-013 | | | | +| TSL-014 | | | | +| TSL-015 | | | | +| TSL-016 | | | | +| TSL-017 | | | | +| TSL-018 | | | | +| TSL-019 | | | | +| TSL-020 | | | | +| TSL-021 | | | | +| TSL-022 | | | | +| TSL-023 | | | | +| TSL-024 | | | | +| TSL-025 | | | | +| TSL-026 | | | | +| TSL-027 | | | | +| TSL-028 | | | | +| TSL-029 | | | | +| TSL-030 | | | | +| TSL-031 | | | | +| TSL-032 | | | | +| TSL-033 | | | | +| TSL-034 | | | | +| TSL-035 | | | | +| TSL-036 | | | | +| TSL-037 | | | | +| TSL-038 | | | | +| TSL-039 | | | | +| TSL-040 | | | | +| TSL-041 | | | | +| TSL-042 | | | | +| TSL-043 | | | | +| TSL-044 | | | | +| TSL-045 | | | | +| TSL-046 | | | | +| TSL-047 | | | | +| TSL-048 | | | | +| TSL-049 | | | | +| TSL-050 | | | | +| TSL-051 | | | | +| TSL-052 | | | | +| TSL-053 | | | | +| TSL-054 | | | | +| TSL-055 | | | | +| TSL-056 | | | | +| TSL-057 | | | | +| TSL-058 | | | | +| TSL-059 | | | | +| TSL-060 | | | | +| TSL-061 | | | | +| TSL-062 | | | | +| TSL-063 | | | | +| TSL-064 | | | | +| TSL-065 | | | | +| TSL-066 | | | | +| TSL-067 | | | | +| TSL-068 | | | | +| TSL-069 | | | | +| TSL-070 | | | | +| TSL-071 | | | | +| TSL-072 | | | | +| TSL-073 | | | | +| TSL-074 | | | | +| TSL-075 | | | | +| TSL-076 | | | | +| TSL-077 | | | | +| TSL-078 | | | | +| TSL-079 | | | | +| TSL-080 | | | | +| TSL-081 | | | | +| TSL-082 | | | | +| TSL-083 | | | | +| TSL-084 | | | | +| TSL-085 | | | | +| TSL-086 | | | | +| TSL-087 | | | | +| TSL-088 | | | | +| TSL-089 | | | | +| TSL-090 | | | | +| TSL-091 | | | | +| TSL-092 | | | | +| TSL-093 | | | | +| TSL-094 | | | | +| TSL-095 | | | | +| TSL-096 | | | | +| TSL-097 | | | | +| TSL-098 | | | | +| TSL-099 | | | | +| TSL-100 | | | | diff --git a/test/agent/test_cases_zh.md b/test/agent/test_cases_zh.md new file mode 100644 index 00000000..ba20a1c5 --- /dev/null +++ b/test/agent/test_cases_zh.md @@ -0,0 +1,3136 @@ +# TSL Agent 代码生成提示测试 + +本文件定义了用于评估 agent 能否阅读 `docs/tsl` 并在首次尝试时生成语法正确的 TSL 代码的手动提示测试。 + +这些不是 TSL 语言文档。它们是 agent 评估提示。语法事实保留在 `docs/tsl` 中；agent 测试提示保留在此处。 + +## 运行方法 + +对于每个测试用例： + +1. 从可访问此仓库的全新 agent 上下文开始。 +2. 仅将 `Prompt` 文本发送给 agent，除非测试运行器有标准系统提示。 +3. 允许 agent 阅读 `docs/tsl`。 +4. 仅对第一个完整答案评分。不允许 agent 修订。 +5. 根据 `Pass criteria` 记录通过/失败。 + +推荐的运行器设置： + +```text +You are in this repository. TSL grammar and reference docs are under docs/tsl. +When asked to write TSL, read the relevant docs/tsl pages first. Do not infer +syntax from Pascal, TypeScript, JavaScript, Python, or SQL. +``` + +## 评分标准 + +- `2` = 首次回答满足所有通过标准。 +- `1` = 基本正确，但有一个不影响被测语法点的小问题。 +- `0` = 错误的文件模型、无效的 TSL 语法、虚构的语法或遗漏了被测语法点。 + +跟踪这些汇总指标： + +- 整体首次通过准确率。 +- 按主题组的准确率。 +- 最常见的失败模式。 +- 失败是否来自未阅读文档、阅读了错误的文档页面或过度拟合到另一种语言。 + +## 全局失败模式 + +只要生成的代码中出现以下情况，就标记为失败： + +- 使用 `=` 进行普通赋值而不是 `:=`。 +- 在类型化参数列表中使用逗号分隔符，例如 `function Add(a: integer, b: integer): integer`。 +- 将命名参数写为 `a = 1` 而不是 `a: 1`。 +- 将 `.tsl` 脚本写为仅包含顶层可复用声明，而请求的是可执行脚本行为。 +- 在 `.tsl` function 或 class 声明部分之后追加可执行脚本语句。 +- 将顶层 class 写为 `class Name ... end;` 而不是 `type Name = class ... end;`。 +- 对 class function 或 static 字段使用裸类名而不是 `class(Name)`。 +- 虚构 `docs/tsl` 中未记录的语法。 + +## 测试用例 + +### TSL-001: 类型化加法函数 + +Prompt: + +```text +请根据本仓库 docs/tsl 的语法，写一个 TSL 加法函数 Add。 +要求两个参数都有整数类型，返回值也要有整数类型。 +只输出代码。 +``` + +Expected focus: + +- 基本的 `function` 声明。 +- 类型化参数和类型化返回值。 + +Pass criteria: + +- 使用 `function Add(a: integer; b: integer): integer;`。 +- 使用 `return a + b;`。 +- 使用 `begin ... end;`。 +- 不用逗号分隔类型化参数。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-002: 调用本地函数的可执行脚本 + +Prompt: + +```text +写一段可执行的 .tsl 脚本：计算 1 + 2，并用 writeLn 输出结果。 +加法逻辑封装成 Add 函数，脚本里调用它。 +只输出代码。 +``` + +Expected focus: + +- `.tsl` 文件模型。 +- 可执行语句在本地函数声明之前。 + +Pass criteria: + +- 脚本语句出现在 `function Add...` 声明之前。 +- 在声明之前调用 `writeLn(Add(1, 2));` 或等效语句。 +- 不在函数声明之后追加可执行语句。 +- 如果引入赋值，使用 `:=` 进行普通赋值。 + +Source docs: + +- `docs/tsl/syntax/01_quickstart.md` +- `docs/tsl/syntax/02_core_model.md` +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-003: 可复用函数文件 + +Prompt: + +```text +我要一个可复用的 .tsf 函数扩展文件，里面只有一个函数 IsPositive， +输入整数 x，返回 x 是否大于 0。只输出代码。 +``` + +Expected focus: + +- `.tsf` 可复用声明模型。 +- 没有可执行脚本入口语句。 + +Pass criteria: + +- 输出顶层 `function IsPositive(x: integer);` 或类型化返回值变体（如果所选证据支持）。 +- 函数体返回 `x > 0`。 +- 不添加 `.tsl` 入口语句，如 `writeLn(...)`。 +- 不虚构未记录的 `boolean` 返回类型。 + +Source docs: + +- `docs/tsl/syntax/01_quickstart.md` +- `docs/tsl/syntax/02_core_model.md` +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-004: 带写回参数的过程 + +Prompt: + +```text +写一段 .tsl 脚本，定义一个过程 Bump，把传入变量加 1。 +脚本里先把 a 设为 1，调用 Bump(a)，再输出 a。只输出代码。 +``` + +Expected focus: + +- 仅在显式请求时使用 `procedure`。 +- `var` 参数写回。 +- `.tsl` 声明部分顺序。 + +Pass criteria: + +- 使用 `procedure Bump(var x);`。 +- 在调用 `Bump(a);` 之前赋值 `a := 1;`。 +- 在 procedure 声明之前输出 `a`。 +- 不在 `procedure` 头上加返回类型。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` +- `docs/tsl/syntax/02_core_model.md` + +### TSL-005: 命名参数调用 + +Prompt: + +```text +写一个 TSL 示例，定义函数 MakePair(a, b)，返回 array(a, b)。 +调用时必须使用命名参数，把 b 传 20，把 a 传 10，并输出两个元素。 +只输出代码。 +``` + +Expected focus: + +- 命名参数语法。 +- Array 索引。 + +Pass criteria: + +- 使用 `MakePair(b: 20, a: 10)` 或等效的命名参数顺序调用函数。 +- 不使用 `MakePair(b = 20, a = 10)`。 +- 使用从零开始的 array 索引读取数组元素。 +- 在 `.tsl` 中保持可执行语句在函数声明之前。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` +- `docs/tsl/syntax/12_matrix_and_collections.md` + +### TSL-006: 默认变量模型 + +Prompt: + +```text +写一段最简单的 TSL 脚本：把 3 赋给 a，把 4 赋给 b， +再输出 a * b。不要做多余声明。只输出代码。 +``` + +Expected focus: + +- 普通变量默认不需要 `var` 声明。 +- 赋值运算符。 + +Pass criteria: + +- 使用 `a := 3;` 和 `b := 4;`。 +- 不使用 `a = 3;` 或 `b = 4;`。 +- 不添加不必要的 `var` 声明。 + +Source docs: + +- `docs/tsl/syntax/04_variables_and_constants.md` +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-007: 显式变量模式 + +Prompt: + +```text +写一段 TSL 脚本，开启 explicit 模式，声明变量 total， +把 total 设置为 0，然后输出它。只输出代码。 +``` + +Expected focus: + +- `{$explicit+}`。 +- 显式 `var` 声明。 + +Pass criteria: + +- 以 `{$explicit+}` 开头或在首次使用未声明变量之前放置。 +- 声明 `var total;`。 +- 使用 `total := 0;` 赋值。 + +Source docs: + +- `docs/tsl/syntax/04_variables_and_constants.md` +- `docs/tsl/syntax/16_lexical_structure_and_compile_options.md` + +### TSL-008: 常量初始化 + +Prompt: + +```text +写一段 TSL 脚本，定义常量 max_count 为 3 + 4， +然后输出 max_count。只输出代码。 +``` + +Expected focus: + +- `const name = value;` 是常量初始化，不是普通赋值。 + +Pass criteria: + +- 使用 `const max_count = 3 + 4;`。 +- 输出 `max_count`。 +- 之后不对 `max_count` 赋值。 + +Source docs: + +- `docs/tsl/syntax/04_variables_and_constants.md` +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-009: 单变量解构 + +Prompt: + +```text +写一段 TSL 脚本，从 array(7, 8, 9) 里只拆出第一个值到 first， +然后输出 first。只输出代码。 +``` + +Expected focus: + +- 单变量解构保留尾随逗号。 + +Pass criteria: + +- 使用 `[first, ] := array(7, 8, 9);`。 +- 不使用 `[first] := ...`。 + +Source docs: + +- `docs/tsl/syntax/04_variables_and_constants.md` +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-010: If Else 块 + +Prompt: + +```text +写一段 TSL 脚本：如果 score >= 60，就把 result 设为 "pass"， +否则设为 "fail"，最后输出 result。score 设为 70。只输出代码。 +``` + +Expected focus: + +- 块式 `if ... then begin ... end else begin ... end`。 +- `then` 块的 `end` 和 `else` 之间没有分号。 + +Pass criteria: + +- 使用 `if score >= 60 then` 后跟有效块。 +- 不在 `then` 分支的 `end` 之后、`else` 之前放置分号。 +- 在条件块之后输出，不是仅在一个分支内输出。 + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-011: 带步长的 For 循环 + +Prompt: + +```text +写一段 TSL 脚本，用 for 循环计算 1、3、5 的和并输出。 +要求使用 step。只输出代码。 +``` + +Expected focus: + +- `for i := 1 to 5 step 2 do`。 + +Pass criteria: + +- 使用 `for i := 1 to 5 step 2 do`。 +- 使用 `:=` 或 `+=` 累加。 +- 输出 `9` 或计算的和变量。 + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-012: Array 遍历 + +Prompt: + +```text +写一段 TSL 脚本，遍历 array(10, 20, 30)，每行输出索引和值的和。 +必须使用 for i, v in data。只输出代码。 +``` + +Expected focus: + +- Array 遍历形式。 +- 从零开始的索引行为。 + +Pass criteria: + +- 使用 `for i, v in data do`。 +- 使用 `data := array(10, 20, 30);`。 +- 不虚构 Python 风格或 JavaScript 风格的迭代语法。 + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-013: Array 和 String 索引 + +Prompt: + +```text +写一段 TSL 脚本，创建 array(10, 20, 30) 和字符串 "ABC"。 +输出数组第一个元素，再输出字符串第一个字符。只输出代码。 +``` + +Expected focus: + +- Array 是从零开始的。 +- String 是从一开始的。 + +Pass criteria: + +- 使用 `arr[0]` 读取第一个数组元素。 +- 使用 `s[1]` 读取第一个字符串字符。 +- 不使用 `s[0]`。 + +Source docs: + +- `docs/tsl/syntax/01_quickstart.md` +- `docs/tsl/syntax/03_values_and_literals.md` +- `docs/tsl/syntax/11_pitfalls.md` + +### TSL-014: 类哈希 Array + +Prompt: + +```text +写一段 TSL 脚本，用 array 创建一个带字符串键的表， +包含 Code = "0001" 和 Price = 12.3，然后输出 Code。只输出代码。 +``` + +Expected focus: + +- `array("Code": "0001", "Price": 12.3)`。 + +Pass criteria: + +- 使用字符串键 `array(...)` 语法。 +- 使用 `hash["Code"]` 或等效变量名读取。 + +Source docs: + +- `docs/tsl/syntax/12_matrix_and_collections.md` + +### TSL-015: in 与 sqlin + +Prompt: + +```text +写一段 TSL 脚本，同时演示： +1 是否属于 array(1, 2)，以及 array(1, 2) 这一整行是否存在于 +array((1, 2), (3, 4))。分别输出两个判断结果。只输出代码。 +``` + +Expected focus: + +- 元素/子集关系使用 `in`。 +- 整行关系使用 `sqlin`。 + +Pass criteria: + +- 使用 `1 in array(1, 2)`。 +- 使用 `array(1, 2) sqlin array((1, 2), (3, 4))`。 +- 不对整行测试使用 `in`。 + +Source docs: + +- `docs/tsl/syntax/12_matrix_and_collections.md` + +### TSL-016: 显式字符串到整数转换 + +Prompt: + +```text +写一段 TSL 脚本，把字符串 "1234" 转成整数后加 1， +再输出结果。只输出代码。 +``` + +Expected focus: + +- 显式转换而不是依赖混合类型算术。 + +Pass criteria: + +- 使用 `strToInt(...)`。 +- 不直接计算 `"1234" + 1`。 + +Source docs: + +- `docs/tsl/syntax/17_types_and_conversions.md` + +### TSL-017: Nil 处理 + +Prompt: + +```text +写一段 TSL 脚本，创建空数组 arr，判断 arr[0] 是否为 nil， +并输出判断结果。只输出代码。 +``` + +Expected focus: + +- 空数组缺失元素返回 `nil`。 +- 显式 nil 比较。 + +Pass criteria: + +- 使用 `arr := array();`。 +- 检查 `arr[0] = nil` 或使用已记录的 `ifNil(...)`。 +- 不虚构 `null`、`None` 或 `undefined`。 + +Source docs: + +- `docs/tsl/syntax/17_types_and_conversions.md` + +### TSL-018: 类正则表达式 Like + +Prompt: + +```text +写一段 TSL 脚本，判断字符串 "abc" 是否匹配以 a 开头的模式， +用 like 运算符，并输出结果。只输出代码。 +``` + +Expected focus: + +- `like` 右侧是类正则表达式，不是 SQL `%` 通配符。 + +Pass criteria: + +- 使用正则风格模式，如 `"^a.*"` 或其他已记录的兼容正则模式。 +- 不使用 `"a%"` 作为模式。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-041: 位运算符 + +Prompt: + +```text +写一段 TSL 脚本，对两个整数演示位与、位或、位非、位异或， +并输出结果。只输出代码。 +``` + +Pass criteria: + +- 使用点前缀位运算符，如 `.&`、`.|`、`.!` 和 `.^`。 +- 不使用普通的 `&`、`|` 或 `~` 作为位运算符。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-042: 复合赋值和自增 + +Prompt: + +```text +写一段 TSL 脚本，a 初始为 1，先用复合赋值加 2， +再自增一次，最后输出 a。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `+=` 和 `a++` 或 `++a`。 +- 使用 `a := 1;` 初始化。 +- 不使用 `a = a + 2`。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-043: Nil 安全访问 + +Prompt: + +```text +写一段 TSL 示例，安全读取可能为 nil 的对象成员 value， +使用 docs/tsl 里的空安全访问写法。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 nil 安全访问，如 `obj?.value`。 +- 不虚构超出已记录模式的可选链式调用形式。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-044: 标量链式比较 + +Prompt: + +```text +写一段 TSL 脚本，判断 1 < 2 < 3 的连续标量比较并输出结果。 +使用 docs/tsl 的链式比较写法。只输出代码。 +``` + +Pass criteria: + +- 使用标量链式比较，如 `1 :< 2 :< 3`。 +- 不写 Python 风格的 `1 < 2 < 3`。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-045: 类矩阵链式比较 + +Prompt: + +```text +写一段 TSL 脚本，对 array(1, 2, -1)、array(2, 1, 0)、array(3, 2, 1) +做逐元素链式小于比较，并输出结果数组的三个元素。只输出代码。 +``` + +Pass criteria: + +- 使用矩阵链式比较，如 `::<`。 +- 使用从零开始的索引读取结果数组元素。 +- 不对数组级比较使用标量 `:<`。 + +Source docs: + +- `docs/tsl/syntax/12_matrix_and_collections.md` +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-046: 默认参数 + +Prompt: + +```text +写一个 TSL 函数 AddOne，参数 a 默认值为 1，返回 a + 1。 +再写脚本输出 AddOne() 和 AddOne(5)。只输出代码。 +``` + +Pass criteria: + +- 使用 `function AddOne(a = 1);`。 +- 在 `.tsl` 声明部分之前调用函数。 +- 不使用不支持的默认参数语法。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-047: 类型化默认参数 + +Prompt: + +```text +写一个 TSL 函数 TypedAdd，参数 a 是 integer，默认值为 1， +返回值是 integer，返回 a + 1。只输出代码。 +``` + +Pass criteria: + +- 使用 `function TypedAdd(a: integer = 1): integer;`。 +- 不用逗号分隔类型化参数。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-048: 跳过中间参数的命名参数 + +Prompt: + +```text +写一段 TSL 脚本，定义 TestFunc(a, b, c)，调用 TestFunc(1, c: 3)， +在函数里输出 b 是否为 nil。只输出代码。 +``` + +Pass criteria: + +- 使用命名参数语法 `c: 3`。 +- 使用 `ifNil(b)` 或已记录的 nil 比较检查跳过的 `b`。 +- 保持可执行调用在函数声明之前。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-049: 带命名参数的 call + +Prompt: + +```text +写一段 TSL 脚本，通过 call 调用 TestFunc，并用命名参数传 a、b、c。 +TestFunc 返回 a * 100 + b * 10 + c。只输出代码。 +``` + +Pass criteria: + +- 使用 `call("TestFunc", a: ..., b: ..., c: ...)`。 +- 不用 `=` 写命名参数。 +- 在 `.tsl` 中的调用之后定义 `TestFunc`。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-050: varByRef 开关 + +Prompt: + +```text +写一段 TSL 脚本，演示 {$varByRef-} 下未修饰参数不写回， +但 var 参数仍会写回。只输出代码。 +``` + +Pass criteria: + +- 使用 `{$varByRef-}`，如果需要则稍后使用 `{$varByRef+}` 恢复。 +- 包含一个未修饰参数函数和一个 `var` 参数函数。 +- 不依赖其他语言的值/引用模型。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` +- `docs/tsl/syntax/16_lexical_structure_and_compile_options.md` +- `docs/tsl/syntax/11_pitfalls.md` + +### TSL-019: 基本 Class + +Prompt: + +```text +写一段 .tsl 脚本，定义 Person 类，包含 public 字段 name。 +脚本里创建 Person，把 name 设为 "Tom"，然后输出 name。只输出代码。 +``` + +Expected focus: + +- 顶层 class 声明语法。 +- `.tsl` 可执行语句在 class 声明部分之前。 + +Pass criteria: + +- 使用 `type Person = class`。 +- 在 `name;` 之前包含 `public`。 +- 使用 `new Person()` 创建。 +- 不写 `class Person`。 +- 不在 class 声明之后追加可执行语句。 + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` +- `docs/tsl/syntax/02_core_model.md` + +### TSL-020: Public 构造函数 + +Prompt: + +```text +写一段 .tsl 脚本，定义 Counter 类。 +构造函数接收初始值 v，保存到 value；Inc 方法把 value 加 1 并返回。 +脚本里 new Counter(10)，输出 Inc 的结果。只输出代码。 +``` + +Expected focus: + +- `public` 下的 `function create(...)` 构造函数。 +- 实例方法体直接访问成员。 + +Pass criteria: + +- 定义 `type Counter = class`。 +- 在 `public` 部分放置 `function create(v);`。 +- 在 `create` 中使用 `value := v;`。 +- 在 `Inc` 中使用 `value := value + 1; return value;` 或等效语句。 +- 不将 `create` 设为 private 或 protected。 + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-021: Static 字段访问 + +Prompt: + +```text +写一段 TSL 示例，定义 THuman 类，包含 static 字段 mCount。 +先把 mCount 设置为 100，再输出它。只输出代码。 +``` + +Expected focus: + +- 通过 class type 访问 static 字段。 + +Pass criteria: + +- 定义 `static mCount;`。 +- 通过 `class(THuman).mCount` 设置或读取。 +- 不使用 `THuman.mCount`。 + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` +- `docs/tsl/syntax/11_pitfalls.md` + +### TSL-022: Class Function 访问 + +Prompt: + +```text +写一个 TSL 类 MathBox，里面有 class function Add(a, b)，返回 a + b。 +再写脚本输出 MathBox 的 Add(1, 2) 结果。只输出代码。 +``` + +Expected focus: + +- Class function 声明。 +- 通过 class type 调用 class function。 + +Pass criteria: + +- 在 `type MathBox = class` 内定义 `class function Add(a, b);`。 +- 通过 `class(MathBox).Add(1, 2)` 或其他已记录的 class-type 路径调用。 +- 不调用 `MathBox.Add(1, 2)`。 +- 在 `.tsl` 中保持可执行调用在 class 声明之前。 + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` +- `docs/tsl/syntax/11_pitfalls.md` + +### TSL-023: 完整 Unit 骨架 + +Prompt: + +```text +写一个 .tsf unit，名字是 DemoUnit。 +对外暴露函数 Ping，调用返回 1。使用完整 interface / implementation 结构。 +只输出代码。 +``` + +Expected focus: + +- 完整的 `unit` 结构。 +- `end.` 终止符。 + +Pass criteria: + +- 以 `unit DemoUnit;` 开头。 +- 有 `interface` 和 `implementation` 部分。 +- 在 `interface` 中声明 `function Ping();`。 +- 实现 `function Ping(); begin return 1; end;`。 +- 以 `end.` 结束 unit。 + +Source docs: + +- `docs/tsl/syntax/09_units_and_scope.md` +- `docs/tsl/syntax/01_quickstart.md` + +### TSL-024: 顶层 uses 在语句之前 + +Prompt: + +```text +写一段 .tsl 脚本，使用 UnitA 和 UnitB 两个 unit， +然后调用 Run() 并输出结果。注意 uses 的位置。只输出代码。 +``` + +Expected focus: + +- 顶层 `uses` 在普通语句之前。 +- 一个 `uses` 语句中包含多个 unit。 + +Pass criteria: + +- 在可执行语句之前使用 `uses UnitA, UnitB;`。 +- 不在顶层 `uses` 之前写普通语句。 +- 默认不生成两个独立的顶层 `uses` 语句。 + +Source docs: + +- `docs/tsl/syntax/09_units_and_scope.md` +- `docs/tsl/syntax/11_pitfalls.md` + +### TSL-025: 函数体 uses 位置 + +Prompt: + +```text +写一个 TSL 函数 RunInFunction，函数体内使用 DemoUnit， +然后返回 Ping()。只输出这个函数代码。 +``` + +Expected focus: + +- 函数体 `uses` 必须是第一条语句。 + +Pass criteria: + +- 将 `uses DemoUnit;` 作为 `begin` 之后的第一条语句。 +- 不在函数体 `uses` 之前放置任何赋值或其他语句。 +- 不在同一个函数体内重复 `uses`。 + +Source docs: + +- `docs/tsl/syntax/09_units_and_scope.md` + +### TSL-026: Try Except + +Prompt: + +```text +写一段 TSL 脚本，用 try/except 捕获 raise "bad"， +在 except 中输出 exceptObject.errInfo。只输出代码。 +``` + +Expected focus: + +- TSL 异常语法。 +- `exceptObject` 字段。 + +Pass criteria: + +- 使用 `try ... except ... end`。 +- 使用 `raise "bad"` 抛出。 +- 在 `except` 块中读取 `exceptObject.errInfo`。 + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-027: 模糊的文件模型 + +Prompt: + +```text +帮我写一个 TSL 的加法函数。 +``` + +Expected focus: + +- 处理未充分指定的用户请求。 +- 避免虚构文件模型假设。 + +Pass criteria: + +- 要么仅生成最小的可复用函数声明，要么在代码之前明确说明文件模型假设。 +- 使用 `function`，不使用 `procedure`。 +- 不生成无效的 `.tsl` 声明排序。 +- 如果提示未要求参数类型，则不虚构参数类型。 + +Source docs: + +- `docs/tsl/index.md` +- `docs/tsl/syntax/01_quickstart.md` +- `docs/tsl/syntax/02_core_model.md` +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-028: 带类型要求的不规范提示 + +Prompt: + +```text +帮我写一个tsl代码，写一个加法，需要参数类型和返回类型。 +``` + +Expected focus: + +- 对非正式中文提示的鲁棒性。 +- 正确的类型化函数语法。 + +Pass criteria: + +- 使用带类型化参数和类型化返回值的 `function`。 +- 在类型化参数之间使用分号。 +- 使用 `return a + b;`。 +- 不使用类似 TypeScript 的语法，如 `function add(a: number, b: number): number`。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-029: 反 Pascal 赋值陷阱 + +Prompt: + +```text +写一段 TSL 脚本，把 a 设为 1，把 b 设为 2， +如果 a + b 等于 3 就输出 "ok"。只输出代码。 +``` + +Expected focus: + +- 普通赋值与相等比较。 + +Pass criteria: + +- 使用 `a := 1;` 和 `b := 2;`。 +- 仅在比较表达式中使用 `=`。 +- 不使用 `==`。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-041: 位运算符 + +Prompt: + +```text +写一段 TSL 脚本，对两个整数演示位与、位或、位非、位异或， +并输出结果。只输出代码。 +``` + +Pass criteria: + +- 使用点前缀位运算符，如 `.&`、`.|`、`.!` 和 `.^`。 +- 不使用普通的 `&`、`|` 或 `~` 作为位运算符。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-042: 复合赋值和自增 + +Prompt: + +```text +写一段 TSL 脚本，a 初始为 1，先用复合赋值加 2， +再自增一次，最后输出 a。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `+=` 和 `a++` 或 `++a`。 +- 使用 `a := 1;` 初始化。 +- 不使用 `a = a + 2`。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-043: Nil 安全访问 + +Prompt: + +```text +写一段 TSL 示例，安全读取可能为 nil 的对象成员 value， +使用 docs/tsl 里的空安全访问写法。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 nil 安全访问，如 `obj?.value`。 +- 不虚构超出已记录模式的可选链式调用形式。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-044: 标量链式比较 + +Prompt: + +```text +写一段 TSL 脚本，判断 1 < 2 < 3 的连续标量比较并输出结果。 +使用 docs/tsl 的链式比较写法。只输出代码。 +``` + +Pass criteria: + +- 使用标量链式比较，如 `1 :< 2 :< 3`。 +- 不写 Python 风格的 `1 < 2 < 3`。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-045: 类矩阵链式比较 + +Prompt: + +```text +写一段 TSL 脚本，对 array(1, 2, -1)、array(2, 1, 0)、array(3, 2, 1) +做逐元素链式小于比较，并输出结果数组的三个元素。只输出代码。 +``` + +Pass criteria: + +- 使用矩阵链式比较，如 `::<`。 +- 使用从零开始的索引读取结果数组元素。 +- 不对数组级比较使用标量 `:<`。 + +Source docs: + +- `docs/tsl/syntax/12_matrix_and_collections.md` +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-046: 默认参数 + +Prompt: + +```text +写一个 TSL 函数 AddOne，参数 a 默认值为 1，返回 a + 1。 +再写脚本输出 AddOne() 和 AddOne(5)。只输出代码。 +``` + +Pass criteria: + +- 使用 `function AddOne(a = 1);`。 +- 在 `.tsl` 声明部分之前调用函数。 +- 不使用不支持的默认参数语法。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-047: 类型化默认参数 + +Prompt: + +```text +写一个 TSL 函数 TypedAdd，参数 a 是 integer，默认值为 1， +返回值是 integer，返回 a + 1。只输出代码。 +``` + +Pass criteria: + +- 使用 `function TypedAdd(a: integer = 1): integer;`。 +- 不用逗号分隔类型化参数。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-048: 跳过中间参数的命名参数 + +Prompt: + +```text +写一段 TSL 脚本，定义 TestFunc(a, b, c)，调用 TestFunc(1, c: 3)， +在函数里输出 b 是否为 nil。只输出代码。 +``` + +Pass criteria: + +- 使用命名参数语法 `c: 3`。 +- 使用 `ifNil(b)` 或已记录的 nil 比较检查跳过的 `b`。 +- 保持可执行调用在函数声明之前。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-049: 带命名参数的 call + +Prompt: + +```text +写一段 TSL 脚本，通过 call 调用 TestFunc，并用命名参数传 a、b、c。 +TestFunc 返回 a * 100 + b * 10 + c。只输出代码。 +``` + +Pass criteria: + +- 使用 `call("TestFunc", a: ..., b: ..., c: ...)`。 +- 不用 `=` 写命名参数。 +- 在 `.tsl` 中的调用之后定义 `TestFunc`。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-050: varByRef 开关 + +Prompt: + +```text +写一段 TSL 脚本，演示 {$varByRef-} 下未修饰参数不写回， +但 var 参数仍会写回。只输出代码。 +``` + +Pass criteria: + +- 使用 `{$varByRef-}`，如果需要则稍后使用 `{$varByRef+}` 恢复。 +- 包含一个未修饰参数函数和一个 `var` 参数函数。 +- 不依赖其他语言的值/引用模型。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` +- `docs/tsl/syntax/16_lexical_structure_and_compile_options.md` +- `docs/tsl/syntax/11_pitfalls.md` + +### TSL-030: 声明后无脚本陷阱 + +Prompt: + +```text +写一段 .tsl 脚本：先调用 Hello()，Hello 输出 "hello"。 +调用完成后再输出 "done"。只输出代码。 +``` + +Expected focus: + +- 所有可执行脚本语句必须在声明部分之前。 +- 自然的提示顺序可能诱使 agent 在 `function Hello` 之后放置 `writeLn("done")`。 + +Pass criteria: + +- 将 `Hello();` 和输出 `"done"` 的语句都放在 `function Hello();` 之前。 +- 在可执行语句之后定义 `Hello`。 +- 不在函数声明之后追加 `"done"` 输出语句。 + +Source docs: + +- `docs/tsl/syntax/01_quickstart.md` +- `docs/tsl/syntax/02_core_model.md` +- `docs/tsl/syntax/11_pitfalls.md` + +## 扩展紧凑用例 + +前 30 个用例是详细的基线用例。以下紧凑用例扩展了语法覆盖范围，同时保持每个提示独立可运行。 + +### TSL-031: 数字字面量类型 + +Prompt: + +```text +写一段 TSL 脚本，分别输出 0x10、0b10、0o10、100L、1E2 的类型判断结果。 +只输出代码。 +``` + +Pass criteria: + +- 使用已记录的数字字面量。 +- 使用类型检查，如 `ifInt`、`ifInt64` 和 `ifReal`。 +- 不将字面量重写为仅十进制值。 + +Source docs: + +- `docs/tsl/syntax/17_types_and_conversions.md` + +### TSL-032: 日期时间字面量 + +Prompt: + +```text +写一段 TSL 脚本，创建 20111231T 和 20101231.0931T， +并分别输出日期和时间字符串。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的日期时间字面量形式。 +- 使用已记录的转换辅助函数，如 `dateToStr` 和 `timeToStr`。 +- 不虚构 ISO 字符串字面量语法。 + +Source docs: + +- `docs/tsl/syntax/17_types_and_conversions.md` + +### TSL-033: Boolean 和数字真值性 + +Prompt: + +```text +写一段 TSL 脚本，输出 true、false，并演示 if 2、if 0、if -1 的判断结果。 +只输出代码。 +``` + +Pass criteria: + +- 直接使用 `true` 和 `false`。 +- 将 `0` 视为 false，将非零数值视为 true。 +- 不虚构 `True` / `False` 大写形式。 + +Source docs: + +- `docs/tsl/syntax/17_types_and_conversions.md` + +### TSL-034: Nil 算术边界 + +Prompt: + +```text +写一段 TSL 脚本，输出 ifNil(nil)、nil + 1、1 + nil， +以及 nil + nil 是否仍为 nil。只输出代码。 +``` + +Pass criteria: + +- 使用 `nil`，不使用 `null`、`None` 或 `undefined`。 +- 使用 `ifNil(nil)` 或已记录的 `nil` 比较。 +- 不将 `nil + 1` 拒绝为无效语法。 + +Source docs: + +- `docs/tsl/syntax/17_types_and_conversions.md` + +### TSL-035: 复数基础 + +Prompt: + +```text +写一段 TSL 脚本，创建复数 4 + 3j 和 complex(5, -2)， +输出第一个复数的 real、imag 和 ifComplex 判断。只输出代码。 +``` + +Pass criteria: + +- 按文档使用 `4 + 3j` 或 `complex(real, imag)`。 +- 使用 `real(...)`、`imag(...)` 和 `ifComplex(...)`。 +- 不虚构 Python 对象方法，如 `.real`。 + +Source docs: + +- `docs/tsl/syntax/17_types_and_conversions.md` + +### TSL-036: 字符串连接 + +Prompt: + +```text +写一段 TSL 脚本，把 "TS" 和 "L" 拼成 "TSL" 并输出。 +使用 docs/tsl 里确认的字符串连接写法。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的字符串连接，用 `+` 或 `$`。 +- 使用 TSL 字符串字面量。 +- 不调用未记录的辅助函数，如 `concat(...)`。 + +Source docs: + +- `docs/tsl/syntax/03_values_and_literals.md` +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-037: 算术运算符覆盖 + +Prompt: + +```text +写一段 TSL 脚本，分别输出 9 div 4、9 mod 4、2 ^ 3、8 ~ 2、3 \ 2。 +只输出代码。 +``` + +Pass criteria: + +- 按文档使用 `div`、`mod`、`^`、`~` 和 `\`。 +- 不用 JavaScript 风格的运算符替换它们。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-041: 位运算符 + +Prompt: + +```text +写一段 TSL 脚本，对两个整数演示位与、位或、位非、位异或， +并输出结果。只输出代码。 +``` + +Pass criteria: + +- 使用点前缀位运算符，如 `.&`、`.|`、`.!` 和 `.^`。 +- 不使用普通的 `&`、`|` 或 `~` 作为位运算符。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-042: 复合赋值和自增 + +Prompt: + +```text +写一段 TSL 脚本，a 初始为 1，先用复合赋值加 2， +再自增一次，最后输出 a。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `+=` 和 `a++` 或 `++a`。 +- 使用 `a := 1;` 初始化。 +- 不使用 `a = a + 2`。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-043: Nil 安全访问 + +Prompt: + +```text +写一段 TSL 示例，安全读取可能为 nil 的对象成员 value， +使用 docs/tsl 里的空安全访问写法。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 nil 安全访问，如 `obj?.value`。 +- 不虚构超出已记录模式的可选链式调用形式。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-044: 标量链式比较 + +Prompt: + +```text +写一段 TSL 脚本，判断 1 < 2 < 3 的连续标量比较并输出结果。 +使用 docs/tsl 的链式比较写法。只输出代码。 +``` + +Pass criteria: + +- 使用标量链式比较，如 `1 :< 2 :< 3`。 +- 不写 Python 风格的 `1 < 2 < 3`。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-045: 类矩阵链式比较 + +Prompt: + +```text +写一段 TSL 脚本，对 array(1, 2, -1)、array(2, 1, 0)、array(3, 2, 1) +做逐元素链式小于比较，并输出结果数组的三个元素。只输出代码。 +``` + +Pass criteria: + +- 使用矩阵链式比较，如 `::<`。 +- 使用从零开始的索引读取结果数组元素。 +- 不对数组级比较使用标量 `:<`。 + +Source docs: + +- `docs/tsl/syntax/12_matrix_and_collections.md` +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-046: 默认参数 + +Prompt: + +```text +写一个 TSL 函数 AddOne，参数 a 默认值为 1，返回 a + 1。 +再写脚本输出 AddOne() 和 AddOne(5)。只输出代码。 +``` + +Pass criteria: + +- 使用 `function AddOne(a = 1);`。 +- 在 `.tsl` 声明部分之前调用函数。 +- 不使用不支持的默认参数语法。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-047: 类型化默认参数 + +Prompt: + +```text +写一个 TSL 函数 TypedAdd，参数 a 是 integer，默认值为 1， +返回值是 integer，返回 a + 1。只输出代码。 +``` + +Pass criteria: + +- 使用 `function TypedAdd(a: integer = 1): integer;`。 +- 不用逗号分隔类型化参数。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-048: 跳过中间参数的命名参数 + +Prompt: + +```text +写一段 TSL 脚本，定义 TestFunc(a, b, c)，调用 TestFunc(1, c: 3)， +在函数里输出 b 是否为 nil。只输出代码。 +``` + +Pass criteria: + +- 使用命名参数语法 `c: 3`。 +- 使用 `ifNil(b)` 或已记录的 nil 比较检查跳过的 `b`。 +- 保持可执行调用在函数声明之前。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-049: 带命名参数的 call + +Prompt: + +```text +写一段 TSL 脚本，通过 call 调用 TestFunc，并用命名参数传 a、b、c。 +TestFunc 返回 a * 100 + b * 10 + c。只输出代码。 +``` + +Pass criteria: + +- 使用 `call("TestFunc", a: ..., b: ..., c: ...)`。 +- 不用 `=` 写命名参数。 +- 在 `.tsl` 中的调用之后定义 `TestFunc`。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-050: varByRef 开关 + +Prompt: + +```text +写一段 TSL 脚本，演示 {$varByRef-} 下未修饰参数不写回， +但 var 参数仍会写回。只输出代码。 +``` + +Pass criteria: + +- 使用 `{$varByRef-}`，如果需要则稍后使用 `{$varByRef+}` 恢复。 +- 包含一个未修饰参数函数和一个 `var` 参数函数。 +- 不依赖其他语言的值/引用模型。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` +- `docs/tsl/syntax/16_lexical_structure_and_compile_options.md` + +### TSL-038: 条件表达式 + +Prompt: + +```text +写一段 TSL 脚本，a 小于 b 时 value 为 10，否则为 20， +要求使用条件表达式并输出 value。只输出代码。 +``` + +Pass criteria: + +- 使用 `condition ? true_value : false_value`。 +- 使用 `:=` 进行赋值。 +- 不错误地虚构 C/JS 的 `?:` 位置。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-041: 位运算符 + +Prompt: + +```text +写一段 TSL 脚本，对两个整数演示位与、位或、位非、位异或， +并输出结果。只输出代码。 +``` + +Pass criteria: + +- 使用点前缀位运算符，如 `.&`、`.|`、`.!` 和 `.^`。 +- 不使用普通的 `&`、`|` 或 `~` 作为位运算符。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-042: 复合赋值和自增 + +Prompt: + +```text +写一段 TSL 脚本，a 初始为 1，先用复合赋值加 2， +再自增一次，最后输出 a。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `+=` 和 `a++` 或 `++a`。 +- 使用 `a := 1;` 初始化。 +- 不使用 `a = a + 2`。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-043: Nil 安全访问 + +Prompt: + +```text +写一段 TSL 示例，安全读取可能为 nil 的对象成员 value， +使用 docs/tsl 里的空安全访问写法。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 nil 安全访问，如 `obj?.value`。 +- 不虚构超出已记录模式的可选链式调用形式。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-044: 标量链式比较 + +Prompt: + +```text +写一段 TSL 脚本，判断 1 < 2 < 3 的连续标量比较并输出结果。 +使用 docs/tsl 的链式比较写法。只输出代码。 +``` + +Pass criteria: + +- 使用标量链式比较，如 `1 :< 2 :< 3`。 +- 不写 Python 风格的 `1 < 2 < 3`。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-045: 类矩阵链式比较 + +Prompt: + +```text +写一段 TSL 脚本，对 array(1, 2, -1)、array(2, 1, 0)、array(3, 2, 1) +做逐元素链式小于比较，并输出结果数组的三个元素。只输出代码。 +``` + +Pass criteria: + +- 使用矩阵链式比较，如 `::<`。 +- 使用从零开始的索引读取结果数组元素。 +- 不对数组级比较使用标量 `:<`。 + +Source docs: + +- `docs/tsl/syntax/12_matrix_and_collections.md` +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-046: 默认参数 + +Prompt: + +```text +写一个 TSL 函数 AddOne，参数 a 默认值为 1，返回 a + 1。 +再写脚本输出 AddOne() 和 AddOne(5)。只输出代码。 +``` + +Pass criteria: + +- 使用 `function AddOne(a = 1);`。 +- 在 `.tsl` 声明部分之前调用函数。 +- 不使用不支持的默认参数语法。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-047: 类型化默认参数 + +Prompt: + +```text +写一个 TSL 函数 TypedAdd，参数 a 是 integer，默认值为 1， +返回值是 integer，返回 a + 1。只输出代码。 +``` + +Pass criteria: + +- 使用 `function TypedAdd(a: integer = 1): integer;`。 +- 不用逗号分隔类型化参数。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-048: 跳过中间参数的命名参数 + +Prompt: + +```text +写一段 TSL 脚本，定义 TestFunc(a, b, c)，调用 TestFunc(1, c: 3)， +在函数里输出 b 是否为 nil。只输出代码。 +``` + +Pass criteria: + +- 使用命名参数语法 `c: 3`。 +- 使用 `ifNil(b)` 或已记录的 nil 比较检查跳过的 `b`。 +- 保持可执行调用在函数声明之前。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-049: 带命名参数的 call + +Prompt: + +```text +写一段 TSL 脚本，通过 call 调用 TestFunc，并用命名参数传 a、b、c。 +TestFunc 返回 a * 100 + b * 10 + c。只输出代码。 +``` + +Pass criteria: + +- 使用 `call("TestFunc", a: ..., b: ..., c: ...)`。 +- 不用 `=` 写命名参数。 +- 在 `.tsl` 中的调用之后定义 `TestFunc`。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-050: varByRef 开关 + +Prompt: + +```text +写一段 TSL 脚本，演示 {$varByRef-} 下未修饰参数不写回， +但 var 参数仍会写回。只输出代码。 +``` + +Pass criteria: + +- 使用 `{$varByRef-}`，如果需要则稍后使用 `{$varByRef+}` 恢复。 +- 包含一个未修饰参数函数和一个 `var` 参数函数。 +- 不依赖其他语言的值/引用模型。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` +- `docs/tsl/syntax/16_lexical_structure_and_compile_options.md` + +### TSL-039: 省略真值的条件表达式 + +Prompt: + +```text +写一段 TSL 脚本，分别输出 2 ?: 9 和 0 ?: 9 的结果。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `value ?: fallback` 形式。 +- 除非保留被测试的表达式形式，否则不重写为普通 `if` 语句。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-041: 位运算符 + +Prompt: + +```text +写一段 TSL 脚本，对两个整数演示位与、位或、位非、位异或， +并输出结果。只输出代码。 +``` + +Pass criteria: + +- 使用点前缀位运算符，如 `.&`、`.|`、`.!` 和 `.^`。 +- 不使用普通的 `&`、`|` 或 `~` 作为位运算符。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-042: 复合赋值和自增 + +Prompt: + +```text +写一段 TSL 脚本，a 初始为 1，先用复合赋值加 2， +再自增一次，最后输出 a。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `+=` 和 `a++` 或 `++a`。 +- 使用 `a := 1;` 初始化。 +- 不使用 `a = a + 2`。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-043: Nil 安全访问 + +Prompt: + +```text +写一段 TSL 示例，安全读取可能为 nil 的对象成员 value， +使用 docs/tsl 里的空安全访问写法。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 nil 安全访问，如 `obj?.value`。 +- 不虚构超出已记录模式的可选链式调用形式。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-044: 标量链式比较 + +Prompt: + +```text +写一段 TSL 脚本，判断 1 < 2 < 3 的连续标量比较并输出结果。 +使用 docs/tsl 的链式比较写法。只输出代码。 +``` + +Pass criteria: + +- 使用标量链式比较，如 `1 :< 2 :< 3`。 +- 不写 Python 风格的 `1 < 2 < 3`。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-045: 类矩阵链式比较 + +Prompt: + +```text +写一段 TSL 脚本，对 array(1, 2, -1)、array(2, 1, 0)、array(3, 2, 1) +做逐元素链式小于比较，并输出结果数组的三个元素。只输出代码。 +``` + +Pass criteria: + +- 使用矩阵链式比较，如 `::<`。 +- 使用从零开始的索引读取结果数组元素。 +- 不对数组级比较使用标量 `:<`。 + +Source docs: + +- `docs/tsl/syntax/12_matrix_and_collections.md` +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-046: 默认参数 + +Prompt: + +```text +写一个 TSL 函数 AddOne，参数 a 默认值为 1，返回 a + 1。 +再写脚本输出 AddOne() 和 AddOne(5)。只输出代码。 +``` + +Pass criteria: + +- 使用 `function AddOne(a = 1);`。 +- 在 `.tsl` 声明部分之前调用函数。 +- 不使用不支持的默认参数语法。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-047: 类型化默认参数 + +Prompt: + +```text +写一个 TSL 函数 TypedAdd，参数 a 是 integer，默认值为 1， +返回值是 integer，返回 a + 1。只输出代码。 +``` + +Pass criteria: + +- 使用 `function TypedAdd(a: integer = 1): integer;`。 +- 不用逗号分隔类型化参数。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-048: 跳过中间参数的命名参数 + +Prompt: + +```text +写一段 TSL 脚本，定义 TestFunc(a, b, c)，调用 TestFunc(1, c: 3)， +在函数里输出 b 是否为 nil。只输出代码。 +``` + +Pass criteria: + +- 使用命名参数语法 `c: 3`。 +- 使用 `ifNil(b)` 或已记录的 nil 比较检查跳过的 `b`。 +- 保持可执行调用在函数声明之前。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-049: 带命名参数的 call + +Prompt: + +```text +写一段 TSL 脚本，通过 call 调用 TestFunc，并用命名参数传 a、b、c。 +TestFunc 返回 a * 100 + b * 10 + c。只输出代码。 +``` + +Pass criteria: + +- 使用 `call("TestFunc", a: ..., b: ..., c: ...)`。 +- 不用 `=` 写命名参数。 +- 在 `.tsl` 中的调用之后定义 `TestFunc`。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-050: varByRef 开关 + +Prompt: + +```text +写一段 TSL 脚本，演示 {$varByRef-} 下未修饰参数不写回， +但 var 参数仍会写回。只输出代码。 +``` + +Pass criteria: + +- 使用 `{$varByRef-}`，如果需要则稍后使用 `{$varByRef+}` 恢复。 +- 包含一个未修饰参数函数和一个 `var` 参数函数。 +- 不依赖其他语言的值/引用模型。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` +- `docs/tsl/syntax/16_lexical_structure_and_compile_options.md` + +### TSL-040: 逻辑运算符 + +Prompt: + +```text +写一段 TSL 脚本，使用 and、or、not 组合两个条件，并输出结果。 +只输出代码。 +``` + +Pass criteria: + +- 使用 `and`、`or` 和 `not`。 +- 不使用 `!` 作为逻辑否定。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-041: 位运算符 + +Prompt: + +```text +写一段 TSL 脚本，对两个整数演示位与、位或、位非、位异或， +并输出结果。只输出代码。 +``` + +Pass criteria: + +- 使用点前缀位运算符，如 `.&`、`.|`、`.!` 和 `.^`。 +- 不使用普通的 `&`、`|` 或 `~` 作为位运算符。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-042: 复合赋值和自增 + +Prompt: + +```text +写一段 TSL 脚本，a 初始为 1，先用复合赋值加 2， +再自增一次，最后输出 a。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `+=` 和 `a++` 或 `++a`。 +- 使用 `a := 1;` 初始化。 +- 不使用 `a = a + 2`。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-043: Nil 安全访问 + +Prompt: + +```text +写一段 TSL 示例，安全读取可能为 nil 的对象成员 value， +使用 docs/tsl 里的空安全访问写法。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 nil 安全访问，如 `obj?.value`。 +- 不虚构超出已记录模式的可选链式调用形式。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-044: 标量链式比较 + +Prompt: + +```text +写一段 TSL 脚本，判断 1 < 2 < 3 的连续标量比较并输出结果。 +使用 docs/tsl 的链式比较写法。只输出代码。 +``` + +Pass criteria: + +- 使用标量链式比较，如 `1 :< 2 :< 3`。 +- 不写 Python 风格的 `1 < 2 < 3`。 + +Source docs: + +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-045: 类矩阵链式比较 + +Prompt: + +```text +写一段 TSL 脚本，对 array(1, 2, -1)、array(2, 1, 0)、array(3, 2, 1) +做逐元素链式小于比较，并输出结果数组的三个元素。只输出代码。 +``` + +Pass criteria: + +- 使用矩阵链式比较，如 `::<`。 +- 使用从零开始的索引读取结果数组元素。 +- 不对数组级比较使用标量 `:<`。 + +Source docs: + +- `docs/tsl/syntax/12_matrix_and_collections.md` +- `docs/tsl/syntax/06_expressions_and_operators.md` + +### TSL-046: 默认参数 + +Prompt: + +```text +写一个 TSL 函数 AddOne，参数 a 默认值为 1，返回 a + 1。 +再写脚本输出 AddOne() 和 AddOne(5)。只输出代码。 +``` + +Pass criteria: + +- 使用 `function AddOne(a = 1);`。 +- 在 `.tsl` 声明部分之前调用函数。 +- 不使用不支持的默认参数语法。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-047: 类型化默认参数 + +Prompt: + +```text +写一个 TSL 函数 TypedAdd，参数 a 是 integer，默认值为 1， +返回值是 integer，返回 a + 1。只输出代码。 +``` + +Pass criteria: + +- 使用 `function TypedAdd(a: integer = 1): integer;`。 +- 不用逗号分隔类型化参数。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-048: 跳过中间参数的命名参数 + +Prompt: + +```text +写一段 TSL 脚本，定义 TestFunc(a, b, c)，调用 TestFunc(1, c: 3)， +在函数里输出 b 是否为 nil。只输出代码。 +``` + +Pass criteria: + +- 使用命名参数语法 `c: 3`。 +- 使用 `ifNil(b)` 或已记录的 nil 比较检查跳过的 `b`。 +- 保持可执行调用在函数声明之前。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-049: 带命名参数的 call + +Prompt: + +```text +写一段 TSL 脚本，通过 call 调用 TestFunc，并用命名参数传 a、b、c。 +TestFunc 返回 a * 100 + b * 10 + c。只输出代码。 +``` + +Pass criteria: + +- 使用 `call("TestFunc", a: ..., b: ..., c: ...)`。 +- 不用 `=` 写命名参数。 +- 在 `.tsl` 中的调用之后定义 `TestFunc`。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-050: varByRef 开关 + +Prompt: + +```text +写一段 TSL 脚本，演示 {$varByRef-} 下未修饰参数不写回， +但 var 参数仍会写回。只输出代码。 +``` + +Pass criteria: + +- 使用 `{$varByRef-}`，如果需要则稍后使用 `{$varByRef+}` 恢复。 +- 包含一个未修饰参数函数和一个 `var` 参数函数。 +- 不依赖其他语言的值/引用模型。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` +- `docs/tsl/syntax/16_lexical_structure_and_compile_options.md` + +### TSL-051: in 和 out 调用前缀 + +Prompt: + +```text +写一段 TSL 脚本，在 {$varByRef-} 下调用 Touch3(in a, out b, c)， +演示只有 b 被写回。只输出代码。 +``` + +Pass criteria: + +- 使用调用端前缀 `in` 和 `out`。 +- 使用 `{$varByRef-}`。 +- 不在函数头中将 `in` / `out` 写为类型注解。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-052: exit 边界 + +Prompt: + +```text +写一段 TSL 脚本，函数 Demo(x) 在 x > 0 时 exit， +否则 return 99；输出 Demo(1) 和 Demo(0)。只输出代码。 +``` + +Pass criteria: + +- 在函数内使用 `exit;`。 +- 对另一个分支使用 `return 99;`。 +- 不将 `exit` 视为返回显式自定义值。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-053: 可变参数求和 + +Prompt: + +```text +写一个 TSL 可变参数函数 SumAll(...)，遍历 Params 求和并返回。 +再输出 SumAll(1, 2, 3, 4)。只输出代码。 +``` + +Pass criteria: + +- 使用 `function SumAll(...);`。 +- 迭代 `Params`。 +- 不虚构 JavaScript rest 语法。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-054: ParamCount 和 RealParamCount + +Prompt: + +```text +写一个 TSL 函数 CountArgs(a, b, ...)，返回 ParamCount * 10 + RealParamCount。 +输出 CountArgs(1, 2, 3, 4)。只输出代码。 +``` + +Pass criteria: + +- 使用 `ParamCount` 和 `RealParamCount`。 +- 在函数头中使用尾随 `...`。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-055: 用 call 转发可变参数 + +Prompt: + +```text +写一段 TSL 脚本，DoFunc(fc, ...) 通过 call(fc, ...) 转发参数给 Sum3。 +输出 DoFunc("Sum3", 1, 2, 3)。只输出代码。 +``` + +Pass criteria: + +- 使用 `call(fc, ...)`。 +- 使用 `function DoFunc(fc, ...);`。 +- 不手动解包固定数量的可变参数。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-056: 匿名函数变量 + +Prompt: + +```text +写一段 TSL 脚本，把匿名函数赋给变量 a， +匿名函数返回 x + y，然后用 call(a, 1, 2) 输出结果。只输出代码。 +``` + +Pass criteria: + +- 使用 `a := function(x, y) begin ... end;`。 +- 通过 `call(a, 1, 2)` 或已记录的 `##a(...)` 调用。 +- 不仅将函数变量作为 `a(1, 2)` 调用。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-057: 匿名函数作为参数 + +Prompt: + +```text +写一段 TSL 脚本，定义 Apply(fun)，内部 call(fun, 2, 3)。 +调用 Apply 时直接传入一个匿名乘法函数。只输出代码。 +``` + +Pass criteria: + +- 将 `function(x, y) begin ... end` 作为参数传递。 +- 在 `Apply` 内使用 `call(fun, 2, 3)`。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-058: findFunction 调用 + +Prompt: + +```text +写一段 TSL 脚本，用 findFunction("Add") 找到 Add 函数， +再用文档支持的函数值调用方式输出 Add(1, 2)。只输出代码。 +``` + +Pass criteria: + +- 使用 `findFunction("Add")`。 +- 使用 `##f(...)` 或 `call(f, ...)` 调用返回的函数。 +- 不直接调用 `f(...)`。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-059: thisFunction 调用 + +Prompt: + +```text +写一段 TSL 脚本，用 thisFunction(Add) 得到函数值， +再通过一个 Call 包装函数调用它。只输出代码。 +``` + +Pass criteria: + +- 使用 `thisFunction(Add)`。 +- 使用 `call(...)` 或已记录的包装器风格调用函数值。 +- 如果使用 `thisFunction`，不引用 `Add`。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-060: 全局函数限定 + +Prompt: + +```text +写一段 TSL 示例，局部函数名和全局/系统函数同名时， +用 docs/tsl 里明确的全局函数限定调用写法。只输出代码。 +``` + +Pass criteria: + +- 使用 `::FuncName(...)` 进行全局/系统函数限定。 +- 不虚构其他语言的命名空间分隔符。 + +Source docs: + +- `docs/tsl/syntax/05_functions_and_calls.md` + +### TSL-061: 带范围的 Case 语句 + +Prompt: + +```text +写一段 TSL 脚本，a 为 4，用 case 判断： +1,2 输出 small；3 到 5 输出 mid；其他输出 other。只输出代码。 +``` + +Pass criteria: + +- 使用 `case a of`。 +- 使用逗号标签和 `3 to 5`。 +- 使用 `else` 并以 `end` 结束。 + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-062: Case 表达式 + +Prompt: + +```text +写一段 TSL 脚本，用 case 表达式给 value 赋值， +a 为 2 时 value 是 "two"，否则是 "other"，然后输出 value。只输出代码。 +``` + +Pass criteria: + +- 使用 `value := case ... of ... else ... end;`。 +- 不在表达式形式的分支内放置 `begin ... end` 块。 + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-063: Repeat Until + +Prompt: + +```text +写一段 TSL 脚本，用 repeat ... until 把 counter 从 3 减到 0， +最后输出 counter。只输出代码。 +``` + +Pass criteria: + +- 使用 `repeat ... until counter = 0;`。 +- 不写 `do while` 语法。 + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-064: While 循环中的 Break + +Prompt: + +```text +写一段 TSL 脚本，用 while true 循环累加 1 到 3， +i 大于 3 时 break，然后输出 sum。只输出代码。 +``` + +Pass criteria: + +- 使用 `while true do`。 +- 在循环内使用 `break;`。 +- 为多语句循环体使用 TSL 块结构。 + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-065: While 循环中的 Continue + +Prompt: + +```text +写一段 TSL 脚本，while 循环 i 从 1 到 4， +跳过 i = 2，只累加其他值并输出 sum。只输出代码。 +``` + +Pass criteria: + +- 对跳过的迭代使用 `continue;`。 +- 不在 `continue` 路径之后放置会导致无限循环的增量。 + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-066: Try Finally + +Prompt: + +```text +写一段 TSL 脚本，用 try/finally，try 中输出 "run"， +finally 中输出 "cleanup"。只输出代码。 +``` + +Pass criteria: + +- 使用 `try ... finally ... end`。 +- 不使用 `catch` 或 JavaScript 风格的异常语法。 + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-067: 异常元数据 + +Prompt: + +```text +写一段 TSL 脚本，raise "bad" 后在 except 中输出 errInfo、errLine、errNo。 +只输出代码。 +``` + +Pass criteria: + +- 使用 `exceptObject.errInfo`、`exceptObject.errLine` 和 `exceptObject.errNo`。 +- 使用 `try ... except ... end`。 + +Source docs: + +- `docs/tsl/syntax/07_control_flow.md` + +### TSL-068: 嵌套 Array 解构 + +Prompt: + +```text +写一段 TSL 脚本，从 array((1, 2), (3, 4)) 拆出 r1 和 r2， +并输出 r1[0]、r1[1]、r2[0]、r2[1]。只输出代码。 +``` + +Pass criteria: + +- 使用 `[r1, r2] := array((1, 2), (3, 4));`。 +- 使用从零开始的索引读取嵌套数组元素。 + +Source docs: + +- `docs/tsl/syntax/04_variables_and_constants.md` +- `docs/tsl/syntax/12_matrix_and_collections.md` + +### TSL-069: 行集合操作 + +Prompt: + +```text +写一段 TSL 脚本，对 left_rows 和 right_rows 做 union2、intersect、minus、outersect。 +只输出代码。 +``` + +Pass criteria: + +- 使用行集合运算符 `union2`、`intersect`、`minus` 和 `outersect`。 +- 不将 `union2` 视为保留重复行。 + +Source docs: + +- `docs/tsl/syntax/12_matrix_and_collections.md` + +### TSL-070: 单列 filterIn + +Prompt: + +```text +写一段 TSL 示例，用 filterIn 按单列从结果集中筛选命中行。 +只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `filterIn(...)` 形式。 +- 不用 `in`/`sqlin` 集合操作替换结果集筛选。 + +Source docs: + +- `docs/tsl/syntax/13_resultset_and_filters.md` + +### TSL-071: filterNotIn + +Prompt: + +```text +写一段 TSL 示例，用 filterNotIn 从结果集中排除命中行。 +只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `filterNotIn(...)` 形式。 +- 当任务要求保留筛选语义时，不使用 `minus`。 + +Source docs: + +- `docs/tsl/syntax/13_resultset_and_filters.md` + +### TSL-072: TS-SQL 最小查询 + +Prompt: + +```text +写一段 TSL 示例，对 array((1, 2), (3, 4)) 使用 TS-SQL 最小查询骨架。 +只输出代码。 +``` + +Pass criteria: + +- 使用语法文档中已记录的 TS-SQL 查询形式。 +- 不虚构普通 SQL 字符串执行。 + +Source docs: + +- `docs/tsl/syntax/14_ts_sql.md` + +### TSL-073: TS-SQL where 和 order by + +Prompt: + +```text +写一段 TSL 示例，使用 TS-SQL 对数组结果集按条件过滤并排序。 +只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `where` 和 `order by` TS-SQL 语法。 +- 除非 TS-SQL 文档记录，否则不使用 SQL `%` 通配符假设。 + +Source docs: + +- `docs/tsl/syntax/14_ts_sql.md` + +### TSL-074: TS-SQL group by + +Prompt: + +```text +写一段 TSL 示例，使用 TS-SQL 按字段 group by，并计算每组统计值。 +只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `group by` TS-SQL 形式。 +- 仅使用已记录的聚合/引用辅助函数。 + +Source docs: + +- `docs/tsl/syntax/14_ts_sql.md` + +### TSL-075: TS-SQL join + +Prompt: + +```text +写一段 TSL 示例，用 TS-SQL join 两个数组结果集。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `join` 形式。 +- 不虚构数据库连接或外部 SQL 执行。 + +Source docs: + +- `docs/tsl/syntax/14_ts_sql.md` + +### TSL-076: Runtime with 星号 + +Prompt: + +```text +写一段 TSL 示例，使用 docs/tsl 中的 with * 块环境写法。 +只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `with *` 语法。 +- 不虚构 Python `with` 语义。 + +Source docs: + +- `docs/tsl/syntax/10_runtime_context_and_with.md` + +### TSL-077: Runtime with 双星号 + +Prompt: + +```text +写一段 TSL 示例，使用 docs/tsl 中的 with ** 块环境写法。 +只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `with **` 语法。 +- 不超出已记录的运行时上下文形式进行泛化。 + +Source docs: + +- `docs/tsl/syntax/10_runtime_context_and_with.md` + +### TSL-078: 网格调用超时 + +Prompt: + +```text +写一段 TSL 示例，用 # 网格调用并带 timeout。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `#Func(...)` 和 `timeout N` 形式。 +- 除非有文档记录，否则不将 `timeout` 转换为普通函数参数。 + +Source docs: + +- `docs/tsl/syntax/10_runtime_context_and_with.md` + +### TSL-079: 全局缓存 + +Prompt: + +```text +写一段 TSL 示例，设置全局缓存、读取全局缓存，并判断缓存是否存在。 +只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `setGlobalCache`、`getGlobalCache` 和 `ifCache`。 +- 不虚构浏览器/本地存储风格的 API。 + +Source docs: + +- `docs/tsl/syntax/10_runtime_context_and_with.md` + +### TSL-080: 条件编译 + +Prompt: + +```text +写一段 TSL 示例，使用 {$ifdef ...} 和 {$else} 做条件编译分支。 +只输出代码。 +``` + +Pass criteria: + +- 使用已记录的编译选项语法。 +- 当任务要求条件编译时，不写运行时 `if`。 + +Source docs: + +- `docs/tsl/syntax/16_lexical_structure_and_compile_options.md` + +### TSL-081: 注释和标识符 + +Prompt: + +```text +写一段 TSL 示例，包含 docs/tsl 支持的注释写法和一个普通标识符赋值。 +只输出代码。 +``` + +Pass criteria: + +- 使用词法结构页面中已记录的注释语法。 +- 使用 `:=` 进行赋值。 + +Source docs: + +- `docs/tsl/syntax/16_lexical_structure_and_compile_options.md` + +### TSL-082: goto 标签 + +Prompt: + +```text +写一段 TSL 示例，使用 goto 跳转到标签并输出结果。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `goto` 和标签语法。 +- 如果与文档不同，不虚构 C 风格标签规则。 + +Source docs: + +- `docs/tsl/syntax/15_debug_and_profiler.md` + +### TSL-083: debugReturn + +Prompt: + +```text +写一段 TSL 示例，使用 debugReturn 提前返回调试值。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `debugReturn` 形式。 +- 除非两者都需要，否则不将其与普通 `return` 混淆。 + +Source docs: + +- `docs/tsl/syntax/15_debug_and_profiler.md` + +### TSL-084: 性能分析计时 + +Prompt: + +```text +写一段 TSL 示例，使用 mtic 和 mtoc 做简单计时。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `mtic` / `mtoc` 形式。 +- 不虚构外部计时 API。 + +Source docs: + +- `docs/tsl/syntax/15_debug_and_profiler.md` + +### TSL-085: External 函数声明 + +Prompt: + +```text +写一个 TSL external 函数声明示例，按 docs/tsl 的最小 external 写法。 +只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `external` 声明形式。 +- 不虚构 C、Python 或 TypeScript 的 FFI 语法。 + +Source docs: + +- `docs/tsl/syntax/18_external_calls_and_threads.md` + +### TSL-086: External 过程声明 + +Prompt: + +```text +写一个 TSL procedure external 示例。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `procedure external` 形式。 +- 不在 procedure 头上放置返回类型。 + +Source docs: + +- `docs/tsl/syntax/18_external_calls_and_threads.md` + +### TSL-087: 原生函数指针包装器 + +Prompt: + +```text +写一段 TSL 示例，按 docs/tsl 包装原生函数指针。只输出代码。 +``` + +Pass criteria: + +- 仅使用已记录的原生函数指针包装器形式。 +- 不虚构原始指针语法。 + +Source docs: + +- `docs/tsl/syntax/18_external_calls_and_threads.md` + +### TSL-088: 线程最小模式 + +Prompt: + +```text +写一段 TSL 线程模式最小正例，按 docs/tsl 的线程示例组织。 +只输出代码。 +``` + +Pass criteria: + +- 使用已记录的线程模式语法。 +- 不虚构 async/await 或 JavaScript 线程语法。 + +Source docs: + +- `docs/tsl/syntax/18_external_calls_and_threads.md` + +### TSL-089: Class Property + +Prompt: + +```text +写一个 TSL 类 Box，字段 value 通过 property Value read/write 访问。 +脚本里设置并输出这个属性。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `property Name read ... write ...` 形式。 +- 使用 `type Box = class`。 +- 使用 `new Box()` 创建。 + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-090: 类型化 Class Property + +Prompt: + +```text +写一个 TSL 类 Person，包含 string 类型字段 name_， +并定义带类型注解的 property Name。只输出代码。 +``` + +Pass criteria: + +- 使用字段类型注解，如 `name_: string;`。 +- 使用已记录的类型化 property 形式。 +- 不虚构 C# property 块。 + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-091: 方法重载 + +Prompt: + +```text +写一个 TSL 类 Calc，包含两个同名 Add 方法，参数个数不同。 +只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `overload` 方法形式。 +- 将方法保持在 `type Calc = class` 内。 + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-092: 继承 + +Prompt: + +```text +写一个 TSL 类 Animal 和继承它的 Dog，Dog 增加一个方法 Speak。 +只输出代码。 +``` + +Pass criteria: + +- 使用 `type Dog = class(Animal)`。 +- 不使用 `extends`。 + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-093: Virtual Override + +Prompt: + +```text +写一个 TSL 父类 Base，虚方法 Name；子类 Child 覆盖 Name。 +脚本里创建 Child 并输出 Name。只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `virtual` 和 `override`。 +- 使用 `type Child = class(Base)`。 +- 使用 `new Child()` 创建。 + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-094: Inherited 方法调用 + +Prompt: + +```text +写一个 TSL 子类方法，在方法里调用父类同名方法后再追加自己的逻辑。 +只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `Inherited` 调用形式。 +- 不虚构 `super.method()` 语法。 + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-095: 类外 Class 方法实现 + +Prompt: + +```text +写一个 TSL 类 Greeter，类内只声明 Say 方法， +在类外用 ClassName.Method 形式实现它。只输出代码。 +``` + +Pass criteria: + +- 使用 class 声明加 `function Greeter.Say(...)` 实现。 +- 不在实现部分之后追加可执行脚本语句。 + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-096: 通过字符串类名 createObject + +Prompt: + +```text +写一段 TSL 示例，用字符串类名通过 createObject 创建本地类实例。 +只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `createObject("ClassName")` 形式。 +- 仅在解释它不是请求的字符串名称路径时使用 `new ClassName()`。 + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-097: 析构函数 + +Prompt: + +```text +写一个 TSL 类，定义无参 destroy 函数，在对象引用设为 nil 时触发清理。 +只输出代码。 +``` + +Pass criteria: + +- 使用 `function destroy();`。 +- 在可执行脚本代码中将对象引用设为 `nil`。 +- 不虚构 `destructor` 关键字。 + +Source docs: + +- `docs/tsl/syntax/08_objects_and_classes.md` + +### TSL-098: FMArray 基础 + +Prompt: + +```text +写一段 TSL 示例，创建 FMArray，判断它是 FMArray，并输出尺寸信息。 +只输出代码。 +``` + +Pass criteria: + +- 使用 FMArray 页面中已记录的 FMArray 构造。 +- 使用已记录的 FMArray 类型/大小辅助函数。 +- 不将普通 `array(...)` 视为自动成为 FMArray。 + +Source docs: + +- `docs/tsl/syntax/23_fmarray.md` + +### TSL-099: 矩阵深入 + +Prompt: + +```text +写一段 TSL 示例，初始化矩阵并使用 mrows、mcols、msize 输出维度。 +只输出代码。 +``` + +Pass criteria: + +- 使用已记录的矩阵初始化。 +- 使用 `mrows`、`mcols` 和 `msize`。 + +Source docs: + +- `docs/tsl/syntax/22_matrix_deep_dive.md` + +### TSL-100: 对象运算符重载 + +Prompt: + +```text +写一个 TSL 类，重载二元 + 运算符，让两个对象相加得到一个新对象。 +只输出代码。 +``` + +Pass criteria: + +- 使用已记录的 `operator +` 重载形式。 +- 将重载实现保持在有效的 `type Name = class` 结构内。 +- 不虚构 Python `__add__` 或 C++ 语法。 + +Source docs: + +- `docs/tsl/syntax/24_object_overloads_and_iteration.md` + +## 结果表模板 + +为每个评估的 agent 复制此表： + +| Case | Score | Failure pattern | Notes | +| ------- | ----: | --------------- | ----- | +| TSL-001 | | | | +| TSL-002 | | | | +| TSL-003 | | | | +| TSL-004 | | | | +| TSL-005 | | | | +| TSL-006 | | | | +| TSL-007 | | | | +| TSL-008 | | | | +| TSL-009 | | | | +| TSL-010 | | | | +| TSL-011 | | | | +| TSL-012 | | | | +| TSL-013 | | | | +| TSL-014 | | | | +| TSL-015 | | | | +| TSL-016 | | | | +| TSL-017 | | | | +| TSL-018 | | | | +| TSL-019 | | | | +| TSL-020 | | | | +| TSL-021 | | | | +| TSL-022 | | | | +| TSL-023 | | | | +| TSL-024 | | | | +| TSL-025 | | | | +| TSL-026 | | | | +| TSL-027 | | | | +| TSL-028 | | | | +| TSL-029 | | | | +| TSL-030 | | | | +| TSL-031 | | | | +| TSL-032 | | | | +| TSL-033 | | | | +| TSL-034 | | | | +| TSL-035 | | | | +| TSL-036 | | | | +| TSL-037 | | | | +| TSL-038 | | | | +| TSL-039 | | | | +| TSL-040 | | | | +| TSL-041 | | | | +| TSL-042 | | | | +| TSL-043 | | | | +| TSL-044 | | | | +| TSL-045 | | | | +| TSL-046 | | | | +| TSL-047 | | | | +| TSL-048 | | | | +| TSL-049 | | | | +| TSL-050 | | | | +| TSL-051 | | | | +| TSL-052 | | | | +| TSL-053 | | | | +| TSL-054 | | | | +| TSL-055 | | | | +| TSL-056 | | | | +| TSL-057 | | | | +| TSL-058 | | | | +| TSL-059 | | | | +| TSL-060 | | | | +| TSL-061 | | | | +| TSL-062 | | | | +| TSL-063 | | | | +| TSL-064 | | | | +| TSL-065 | | | | +| TSL-066 | | | | +| TSL-067 | | | | +| TSL-068 | | | | +| TSL-069 | | | | +| TSL-070 | | | | +| TSL-071 | | | | +| TSL-072 | | | | +| TSL-073 | | | | +| TSL-074 | | | | +| TSL-075 | | | | +| TSL-076 | | | | +| TSL-077 | | | | +| TSL-078 | | | | +| TSL-079 | | | | +| TSL-080 | | | | +| TSL-081 | | | | +| TSL-082 | | | | +| TSL-083 | | | | +| TSL-084 | | | | +| TSL-085 | | | | +| TSL-086 | | | | +| TSL-087 | | | | +| TSL-088 | | | | +| TSL-089 | | | | +| TSL-090 | | | | +| TSL-091 | | | | +| TSL-092 | | | | +| TSL-093 | | | | +| TSL-094 | | | | +| TSL-095 | | | | +| TSL-096 | | | | +| TSL-097 | | | | +| TSL-098 | | | | +| TSL-099 | | | | +| TSL-100 | | | | diff --git a/tests/cli/test_claude_md_sync.py b/test/cli/test_claude_md_sync.py similarity index 100% rename from tests/cli/test_claude_md_sync.py rename to test/cli/test_claude_md_sync.py diff --git a/tests/cli/test_install_skills.py b/test/cli/test_install_skills.py similarity index 100% rename from tests/cli/test_install_skills.py rename to test/cli/test_install_skills.py diff --git a/tests/cli/test_playbook_cli.py b/test/cli/test_playbook_cli.py similarity index 100% rename from tests/cli/test_playbook_cli.py rename to test/cli/test_playbook_cli.py diff --git a/tests/cli/test_sync_standards_cli.py b/test/cli/test_sync_standards_cli.py similarity index 100% rename from tests/cli/test_sync_standards_cli.py rename to test/cli/test_sync_standards_cli.py diff --git a/tests/integration/check_doc_links.sh b/test/integration/check_doc_links.sh similarity index 100% rename from tests/integration/check_doc_links.sh rename to test/integration/check_doc_links.sh diff --git a/test/templates/ci_validation_report.txt b/test/templates/ci_validation_report.txt new file mode 100644 index 00000000..8d5d1820 --- /dev/null +++ b/test/templates/ci_validation_report.txt @@ -0,0 +1,11 @@ +CI 模板验证报告 +==================== + +验证时间: 2026-06-21 06:14:22 +模板目录: /home/csh/windows_share/tinysoft/playbook/templates/ci + +统计结果: + 通过: 12 + 失败: 0 + 通过率: 100.0% + diff --git a/test/templates/cpp_validation_report.txt b/test/templates/cpp_validation_report.txt new file mode 100644 index 00000000..e02cabd4 --- /dev/null +++ b/test/templates/cpp_validation_report.txt @@ -0,0 +1,11 @@ +C++ 模板验证报告 +==================== + +验证时间: 2026-06-21 06:14:22 +模板目录: /home/csh/windows_share/tinysoft/playbook/templates/cpp + +统计结果: + 通过: 24 + 失败: 0 + 通过率: 100.0% + diff --git a/test/templates/project_templates_report.txt b/test/templates/project_templates_report.txt new file mode 100644 index 00000000..eaa43601 --- /dev/null +++ b/test/templates/project_templates_report.txt @@ -0,0 +1,11 @@ +项目模板验证报告 +==================== + +验证时间: 2026-06-21 06:08:57 +模板目录: /home/csh/windows_share/tinysoft/playbook/templates + +统计结果: + 通过: 23 + 失败: 0 + 通过率: 100.0% + diff --git a/test/templates/python_validation_report.txt b/test/templates/python_validation_report.txt new file mode 100644 index 00000000..5d1a496c --- /dev/null +++ b/test/templates/python_validation_report.txt @@ -0,0 +1,11 @@ +Python 模板验证报告 +==================== + +验证时间: 2026-06-21 06:14:22 +模板目录: /home/csh/windows_share/tinysoft/playbook/templates/python + +统计结果: + 通过: 25 + 失败: 0 + 通过率: 100.0% + diff --git a/tests/templates/validate_ci_templates.sh b/test/templates/validate_ci_templates.sh similarity index 100% rename from tests/templates/validate_ci_templates.sh rename to test/templates/validate_ci_templates.sh diff --git a/tests/templates/validate_cpp_templates.sh b/test/templates/validate_cpp_templates.sh similarity index 100% rename from tests/templates/validate_cpp_templates.sh rename to test/templates/validate_cpp_templates.sh diff --git a/tests/templates/validate_project_templates.sh b/test/templates/validate_project_templates.sh similarity index 100% rename from tests/templates/validate_project_templates.sh rename to test/templates/validate_project_templates.sh diff --git a/tests/templates/validate_python_templates.sh b/test/templates/validate_python_templates.sh similarity index 100% rename from tests/templates/validate_python_templates.sh rename to test/templates/validate_python_templates.sh diff --git a/tests/test_deployment_routes_e2e.py b/test/test_deployment_routes_e2e.py similarity index 100% rename from tests/test_deployment_routes_e2e.py rename to test/test_deployment_routes_e2e.py diff --git a/tests/test_firstparty_skills_quality.py b/test/test_firstparty_skills_quality.py similarity index 100% rename from tests/test_firstparty_skills_quality.py rename to test/test_firstparty_skills_quality.py diff --git a/tests/test_format_md_action.py b/test/test_format_md_action.py similarity index 100% rename from tests/test_format_md_action.py rename to test/test_format_md_action.py diff --git a/tests/test_gitattributes_modes.py b/test/test_gitattributes_modes.py similarity index 100% rename from tests/test_gitattributes_modes.py rename to test/test_gitattributes_modes.py diff --git a/tests/test_gitea_workflow_bootstrap.py b/test/test_gitea_workflow_bootstrap.py similarity index 100% rename from tests/test_gitea_workflow_bootstrap.py rename to test/test_gitea_workflow_bootstrap.py diff --git a/tests/test_main_loop_cli.py b/test/test_main_loop_cli.py similarity index 99% rename from tests/test_main_loop_cli.py rename to test/test_main_loop_cli.py index f9bee94f..c068d2e3 100644 --- a/tests/test_main_loop_cli.py +++ b/test/test_main_loop_cli.py @@ -34,8 +34,6 @@ def valid_plan_text(title: str = "Demo Plan") -> str: "", "## Plan Meta", "", - "- **Plan Group**: `demo`", - "- **Parent Plan**: `none`", "- **Verification Scope**: `unit`", "- **Verification Gate**: `python -m unittest tests.test_main_loop_cli`", "", diff --git a/tests/test_no_backup_flags.py b/test/test_no_backup_flags.py similarity index 100% rename from tests/test_no_backup_flags.py rename to test/test_no_backup_flags.py diff --git a/tests/test_playbook_docs_index.py b/test/test_playbook_docs_index.py similarity index 100% rename from tests/test_playbook_docs_index.py rename to test/test_playbook_docs_index.py diff --git a/tests/test_script_line_endings.py b/test/test_script_line_endings.py similarity index 100% rename from tests/test_script_line_endings.py rename to test/test_script_line_endings.py diff --git a/tests/test_skills_readme.py b/test/test_skills_readme.py similarity index 100% rename from tests/test_skills_readme.py rename to test/test_skills_readme.py diff --git a/tests/test_sync_directory_actions.py b/test/test_sync_directory_actions.py similarity index 100% rename from tests/test_sync_directory_actions.py rename to test/test_sync_directory_actions.py diff --git a/tests/test_sync_templates_placeholders.py b/test/test_sync_templates_placeholders.py similarity index 93% rename from tests/test_sync_templates_placeholders.py rename to test/test_sync_templates_placeholders.py index 582d85ff..175caa9f 100644 --- a/tests/test_sync_templates_placeholders.py +++ b/test/test_sync_templates_placeholders.py @@ -179,20 +179,13 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase): rules_template = (ROOT / "templates" / "AGENT_RULES.template.md").read_text( encoding="utf-8" ) - self.assertIn("唯一流程约束中心", rules_template) + self.assertIn("框架流程约束基线", rules_template) self.assertIn("{{PLAYBOOK_ROOT}}", rules_template) self.assertIn("Playbook 模板/供应商目录", rules_template) self.assertIn("唯一设计与计划产物中心", rules_template) self.assertIn("memory-bank/progress.md", rules_template) - self.assertIn("已有 `in-progress` 优先恢复", rules_template) - self.assertIn("按 Plan 文件顺序选择第一个可执行 Plan", rules_template) - self.assertIn( - "归档指按当前项目约定创建可回溯的交付记录", - rules_template, - ) - self.assertIn("具体机制由项目本地规则", rules_template) - self.assertIn("或用户指令定义", rules_template) - self.assertIn("memory 更新或回复摘要也不等同于归档", rules_template) + self.assertIn("优先恢复 `in-progress`", rules_template) + self.assertIn("选择第一个可执行 Plan", rules_template) self.assertIn( "`main_loop.py finish -status done` 只负责写回机器状态", rules_template, @@ -204,17 +197,17 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase): "spec/plan 产出阶段不单独提交或归档", rules_template ) self.assertIn( - "如外部 skill 要求写完 spec 或 plan 后立即提交", rules_template + "如外部 skill", rules_template ) self.assertIn("Plan 范围是归档/提交边界", rules_template) self.assertIn( - "不得由 `main_loop.py finish` 自动执行提交或变更归档", + "不自动提交或归档", rules_template, ) self.assertIn("当前 Plan 文件", rules_template) self.assertIn("`memory-bank/progress.md`", rules_template) self.assertIn("必要 memory 更新", rules_template) - self.assertIn("允许存在其他 session 的未归档改动", rules_template) + self.assertIn("允许其未归档共存", rules_template) self.assertIn("当前 Plan 无遗留差异", rules_template) self.assertIn("状态已写回，交付未完成", rules_template) self.assertNotIn("如项目使用 Git", rules_template) @@ -281,9 +274,11 @@ langs = [\"cpp\", \"tsl\"] "记录 `plan=`、`executor=executing-plans`、", rules_text, ) - self.assertIn("未领取 Plan 前，不得直接进入 `$executing-plans`", rules_text) - self.assertIn("默认执行使用 `$executing-plans`", rules_text) - self.assertIn("不是默认执行器", rules_text) + self.assertIn("领取前不得进入 `$executing-plans`", rules_text) + self.assertIn( + "`$subagent-driven-development` 仅在 Plan 或平台明确要求时使用", + rules_text, + ) self.assertNotIn("{{PLAYBOOK_SCRIPTS}}", rules_text) self.assertNotIn("{{PLAYBOOK_ROOT}}", rules_text) self.assertFalse(rules_text.endswith("\n\n")) diff --git a/tests/test_thirdparty_skill_curation.py b/test/test_thirdparty_skill_curation.py similarity index 100% rename from tests/test_thirdparty_skill_curation.py rename to test/test_thirdparty_skill_curation.py diff --git a/tests/test_thirdparty_skills_pipeline.py b/test/test_thirdparty_skills_pipeline.py similarity index 100% rename from tests/test_thirdparty_skills_pipeline.py rename to test/test_thirdparty_skills_pipeline.py diff --git a/tests/test_toml_edge_cases.py b/test/test_toml_edge_cases.py similarity index 100% rename from tests/test_toml_edge_cases.py rename to test/test_toml_edge_cases.py diff --git a/tests/test_tsl_entrypoints_consistency.py b/test/test_tsl_entrypoints_consistency.py similarity index 93% rename from tests/test_tsl_entrypoints_consistency.py rename to test/test_tsl_entrypoints_consistency.py index 28a9d8b1..8e29a97e 100644 --- a/tests/test_tsl_entrypoints_consistency.py +++ b/test/test_tsl_entrypoints_consistency.py @@ -27,6 +27,7 @@ REMOVED_TSL_GUIDE = ROOT / "skills" / "tsl-guide" TSL_REFERENCE_INDEX = ROOT / "docs" / "tsl" / "reference" / "index.md" TSL_REFERENCE_UNAVAILABLE = ROOT / "docs" / "tsl" / "reference" / "unavailable_methods.md" TSL_MODULES_INDEX = ROOT / "docs" / "tsl" / "modules" / "index.md" +TSL_TOOLCHAIN = ROOT / "docs" / "tsl" / "toolchain.md" TSL_REMAINING_SYNTAX_AGENT_SECTIONS = { "07_control_flow.md": "智能体控制流判断流程", @@ -83,13 +84,15 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): def test_ruleset_lists_canonical_tsl_layers(self): text = RULESET_TSL.read_text(encoding="utf-8") self.assertIn("docs/tsl/index.md", text) - self.assertIn("docs/tsl/syntax/index.md", text) self.assertIn("docs/tsl/reference/catalog/datawarehouse.md", text) self.assertIn("docs/tsl/modules/pytsl_api.md", text) self.assertIn("docs/tsl/modules/tsbacktesting.md", text) self.assertIn("docs/tsl/modules/index.md", text) self.assertIn("docs/tsl/reference/index.md", text) + tsl_index = (ROOT / "docs/tsl/index.md").read_text(encoding="utf-8") + self.assertIn("syntax/index.md", tsl_index) + def test_readme_only_lists_two_official_deployment_routes(self): text = README.read_text(encoding="utf-8") self.assertIn("方式一：git subtree", text) @@ -141,27 +144,25 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): text = RULESET_TSL.read_text(encoding="utf-8") self.assertIn("# TSL 智能体规则", text) - self.assertIn("高优先级智能体决策规则", text) + self.assertEqual(len(text.splitlines()), 45) + self.assertIn("作用：控制智能体在阅读、修改、生成 TSL 代码前的判断顺序", text) + self.assertIn("本文件不是 TSL 语法手册", text) + self.assertIn("禁止凭 Pascal、Python、JavaScript、TypeScript", text) self.assertIn("代码生成协议", text) self.assertIn("TSL 核心事实", text) self.assertIn("任务路由", text) self.assertIn("文档事实使用策略", text) - self.assertIn("最终 TSL 自检", text) - self.assertIn("`.tsl` 在通用 TSL 规则中表示可执行脚本", text) - self.assertIn("可执行语句必须位于前部", text) - self.assertIn("声明区", text) - self.assertIn("`.tsf` 表示可复用函数、过程、类、模块或扩展文件", text) - self.assertIn("funcext", text) - self.assertIn("创建对象有两种方式：`new ClassName()` 最常用", text) - self.assertIn("生成代码前向用户确认", text) - self.assertIn("不要因为 Pascal", text) - self.assertIn("代码块身份：可直接照写示例", text) - self.assertIn("不代表 TSL 语法事实", text) - self.assertNotIn("Style Snapshot", text) - self.assertNotIn("## Skills", text) - self.assertNotIn("## 与开发规范的关系", text) - self.assertNotIn("`.tsl` 仅 `function`", text) - self.assertNotIn("脚本优先 `.tsl`，可复用扩展优先 `.tsf`", text) + self.assertRegex( + text, + r"\| 语法、文件模型、最短骨架、反例\s+\| `docs/tsl/index\.md`\s+\|", + ) + self.assertNotIn("最终 TSL 自检", text) + self.assertNotIn("修改纪律", text) + self.assertNotIn("文档入口", text) + self.assertNotIn("## 安全规则", text) + self.assertNotIn("`docs/tsl/index.md` 或 `docs/tsl/syntax/index.md`", text) + self.assertNotIn("代码块身份：可直接照写示例", text) + self.assertNotIn("funcext", text) def test_tsl_syntax_docs_keep_script_then_declarations_model(self): quickstart = (ROOT / "docs/tsl/syntax/01_quickstart.md").read_text( @@ -211,6 +212,23 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): for phrase in forbidden_phrases: self.assertNotIn(phrase, text, msg=f"{phrase!r} found in {path}") + def test_tsl_reader_entrypoints_are_decision_routes_not_agent_process_docs(self): + entrypoints = [ + ROOT / "docs/tsl/index.md", + ROOT / "docs/tsl/syntax/index.md", + ] + + for path in entrypoints: + with self.subTest(path=path.relative_to(ROOT)): + text = path.read_text(encoding="utf-8") + self.assertIn("任务信号", text) + self.assertIn("入口", text) + self.assertIn("阻断条件", text) + self.assertNotIn("智能体语法判断流程", text) + self.assertNotIn("智能体提交前最低自检", text) + self.assertNotIn("本套 TSL 文档面向智能体决策", text) + self.assertNotIn("## 决策顺序", text) + def test_tsl_docs_use_compact_uncertain_header(self): docs_root = ROOT / "docs" / "tsl" @@ -222,11 +240,70 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): def test_tsl_index_uses_documented_generation_facts(self): text = (ROOT / "docs/tsl/index.md").read_text(encoding="utf-8") - self.assertIn("语法事实使用规则", text) - self.assertIn("写成语法事实的内容就是生成依据", text) - self.assertIn("智能体自行证明", text) - self.assertIn("文档没有覆盖的写法不能生成", text) - self.assertIn("执行环境细节不写进语法页", text) + self.assertIn("证据规则", text) + self.assertIn("停止条件", text) + self.assertIn("代码外形缺少 `代码块身份：可直接照写示例`", text) + self.assertIn("无文档事实、文件模型不明或项目执行事实缺失", text) + self.assertIn("语法页不承载执行环境、账户体系、真实接口或验证命令", text) + self.assertIn("项目执行信息会被写成通用 TSL 事实", text) + self.assertNotIn("## 路由冲突", text) + self.assertNotIn("## 生成前阻断条件", text) + + def test_tsl_toolchain_is_template_not_execution_authority(self): + text = TSL_TOOLCHAIN.read_text(encoding="utf-8") + + self.assertIn("# TSL 工具链与验证命令模板", text) + self.assertIn("文档类型：项目工具链模板页", text) + self.assertIn("不是通用执行手册", text) + self.assertIn("不是 TSL 语法事实", text) + self.assertIn("目标项目已真实填写", text) + self.assertIn("仍有 `<...>` 占位符时", text) + self.assertIn("不能作为执行依据", text) + self.assertIn("不提供真实可执行命令", text) + self.assertNotIn("真实 CLI 示例", text) + + def test_tsl_execution_routes_do_not_treat_toolchain_template_as_facts(self): + tsl_index = (ROOT / "docs" / "tsl" / "index.md").read_text(encoding="utf-8") + code_style = (ROOT / "docs" / "tsl" / "code_style.md").read_text( + encoding="utf-8" + ) + readme = README.read_text(encoding="utf-8") + + self.assertIn( + "目标项目已真实填写且没有 `<...>` 占位符的 [toolchain.md](toolchain.md)", + tsl_index, + ) + self.assertIn("验证命令或自动化入口", code_style) + self.assertIn("目标项目已真实填写且没有 `<...>` 占位符的 [toolchain.md](toolchain.md)", code_style) + self.assertNotIn( + "遇到不确定时：[naming.md](naming.md)、[syntax/index.md](syntax/index.md)、[toolchain.md](toolchain.md)", + code_style, + ) + self.assertIn("已填写工具链事实", readme) + self.assertIn("模板未填写时不可作为执行依据", readme) + self.assertNotIn("完整语言手册、代码风格、工具链 | 最终权威", readme) + + def test_tsl_naming_and_code_style_delegate_file_model_facts_to_core_model(self): + naming = (ROOT / "docs" / "tsl" / "naming.md").read_text(encoding="utf-8") + code_style = (ROOT / "docs" / "tsl" / "code_style.md").read_text( + encoding="utf-8" + ) + + self.assertIn("本页只规定命名后的实体如何取名", naming) + self.assertIn("syntax/02_core_model.md", naming) + self.assertNotIn("文件只能有一个顶层声明", naming) + self.assertNotIn("文件基名必须与该顶层声明名字一致", naming) + self.assertNotIn("部署到解释器 `funcext`", naming) + self.assertNotIn("语句区按顺序执行", naming) + self.assertNotIn("语句区在前，声明区在后", naming) + self.assertNotIn("语句区在前，并按顺序执行", naming) + + self.assertIn("文件模型和顶层声明规则以", code_style) + self.assertIn("syntax/02_core_model.md", code_style) + self.assertNotIn("语句区在前并按顺序执行", code_style) + self.assertNotIn("部署到解释器 `funcext`", code_style) + self.assertNotIn("每个 `.tsf` 文件只能有一个顶层声明", code_style) + self.assertNotIn("文件基名必须与顶层声明同名", code_style) def test_tsl_syntax_docs_do_not_keep_stale_manual_sequence_metadata(self): self.assertFalse((ROOT / "docs/tsl/syntax/01_introduction.md").exists())